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1. Introduction to Interactive Streams 



An interactive stream is a bidirectional stream designed for interaction with human 
users. It supports input editing, which lets the user edit input before a function 
that reads from the stream sees it. Interactive streams are built on the flavor 
si:interactive-stream. 

si:interactive-stream Flavor 

A stream that includes this flavor is interactive, or designed for interaction 
with a human user. The stream supports input editing. To fins out 
whether or not a stream is interactive, send the stream an :interactive 
message. 

interactive Message 

The interactive message to a stream returns t if the stream is interactive 
and nil if it is not. Interactive streams, built on sirinteractive-stream, are 
streams designed for interaction with human users. They support input 
editing. Use the interactive message to find out whether a stream 
supports the :input-editor message. 

Interactive streams are generally connected to a terminal of some kind. Windows 
built on tv:stream-mixin are one kind of interactive stream: See the section "Input 
From Windows", page 132. Remote terminals are another: See the section "Remote 
Login" in Networks. 

Some reading functions can be used to get input from both interactive and 
noninteractive streams; others are designed to read only from interactive streams. 
See the section "Input Functions for Interactive Streams", page 5. 

Interactive streams support general operations on input and output streams. For 
more information on these operations: See the section "I/O Streams" in Reference 
Guide to Streams, Files, and I/O. Interactive streams also have specialized input 
operations, mainly to handle interactions with the input editor: See the section 
"Messages for Input From Interactive Streams", page 11. They also intercept some 
characters when read and maintain a list of characters to be handled 
asynchronously: See the section "Intercepted Characters", page 15. See the section 
"Interactive-stream Operations for Asynchronous Characters", page 17. (Remote 
terminals do not handle asynchronous characters.) 

Some interactive streams can display mouse-sensitive items. See the section 
"Interactive Streams and Mouse-sensitive Items", page 19. 

For information on the program interface to the input editor: See the section "The 
Input Editor Program Interface", page 21. 

The command processor is a utility that reads commands from an interactive stream. 
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For more information: See the section "The Command Processor User Interface". 
See the section "The Command Processor Program Interface", page 41. 

One common use for interactive streams is to ask a question of the user: See the 
section "Querying the User", page 55. 
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2. Input Functions for Interactive Streams 



The general reading functions like read, readline, and read-delimited-string can 
be used to read from either interactive or noninteractive streams. See the section 
"Input Functions" in Reference Guide to Streams, Files, and I/O. The functions 
described here are designed to read only from interactive streams. The functions 
that read command processor commands, read-command and 
read-command-or-form, are described elsewhere: See the section "The Command 
Processor Reader", page 41. 

sys:read-character &optional stream &key (fresh-line t) (any-tyi nil) Function 

(eof nil) (notification t) (prompt nil) (kelp nil) 
(refresh t) (suspend t) (abort t) (status nil) 
Reads and returns a single character from stream. This function displays 
notifications and help messages and reprompts at appropriate times. It is 
used by fquery and the character option for prompt-and-read. 

stream must be interactive. It defaults to query-io. 

Following are the permissible keywords: 



:fresh-line 



:any-tyi 



:eof 



motification 



rprompt 



:help 



If not nil, the function sends the stream a :fresh-line 
message before displaying the prompt. If nil, it does not 
send a :fresh-line message. The default is t. 

If not nil, the function returns blips. If nil, blips are 
treated as the :tyi message to an interactive stream treats 
them. The default is nil. 

If not nil and the function encounters end-of-file, it 
returns nil. If nil and the function encounters end-of-file, 
it beeps and waits for more input. The default is nil. 

If not nil and a notification is received, the function 
displays the notification and reprompts. If nil and a 
notification is received, the notification is ignored. The 
default is t. 

If nil, no prompt is displayed. Otherwise, the value should 
be a prompt option to be displayed at appropriate times. 
See the section "Displaying Prompts in the Input Editor", 
page 33. The default is nil. 

If not nil, the value should be a help option. See the 
section "Displaying Help Messages in the Input Editor", 
page 34. Then, when the user presses HELP, the function 
displays the help option and reprompts. If nil and the 
user presses help, the function just returns #\help. The 
default is nil. 
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rrefresh 



:suspend 



:abort 



tstatus 



If not nil and the user presses refresh, the function sends 
the stream a :clear-window message and reprompts. If 
nil and the user presses REFRESH, the function just returns 
#\refresh. The default is t. 

If not nil and the user types one of the 
sys:kbd-standard-suspend-characters, a break loop is 
entered. If nil and the user types a suspend character, 
the function just returns the character. The default is t. 

If not nil and the user types one of the 
sys:kbd-standard-abort-characters, sysrabort is 

signalled. If nil and the user types an abort character, 
the function just returns the character. The default is t. 



This option takes effect only if the stream is a window. If 
the value is :selected and the window is no longer 
selected, the function returns rstatus. If the value is 
rexposed and the window is no longer exposed or selected, 
the function returns rstatus. If the value is nil, the 
function continues to wait for input when the window is 
deexposed or deselected. The default is nil. 

read-expression &optional stream &key (completion-alist nil) Function 

(completion-delimiters nil) 
This is like read-for-top-level, except that if it encounters a top-level end-of- 
file it just beeps and waits for more input. This function is used by the 
expression option for prompt-and-read. 



stream defaults to standard-input. 
from interactive streams. 



This function is intended to read only 



If completion-alist is not nil, this function also sets up complete and c-? as 
input editor commands. When the user presses complete, the input editor 
tries to complete the current symbol over the set of possibilities defined by 
completion-alist. When the user presses c-?, the input editor displays the 
possible completions of the current symbol. 



The style of completion is the same as that offered by Zwei. 
can be nil, an alist, an art-q-list array, or a keyword: 



completion-alist 



nil 

alist 

array 
keyword 



No completion is offered. 

The car of each alist element is a string representing one 
possible completion. 

Each element is a list whose car is a string representing 
one possible completion. The array must be sorted 
alphabetically on the cars of the elements. 

If the symbol is :zmacs, completion is offered over the 
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definitions in Zmacs buffers. If the symbol is iflavors, 
completion is offered over all flavor names. 

The default for completion-alist is nil. 

completion-delimiters is nil or a list of characters that delimit "chunks" for 
completion. As in Zwei, completion works by matching initial substrings of 
"chunks" of text. If completion-delimiters is nil, the entire text of the 
current symbol is a single "chunk". The default is nil. 

read-form &optional stream &key (edit-trivial-errors-p Function 

*read-form-edit-trivial-errors-p*) 

(completion-alist *read-form-completion-alist*) 

(completion-delimiters 

*read-form-completion-delimiters*) 
This function is like read-expression, except that it assumes that the 
returned value will be given immediately to eval. This function is used by 
the Lisp command loop and by the :eval-form and :eval-form-or-end 
options for prompt-and-read. 

stream defaults to standard-input. This function is intended to read only 
from interactive streams. 

If edit-trivial-errors-p is not nil, the function checks for two kinds of errors. 
If a symbol is read, it checks whether the symbol is bound. If a list whose 
first element is a symbol is read, it checks whether the symbol has a function 
definition. If it finds an unbound symbol or undefined function, it offers to 
use a lookalike symbol in another package or calls parse-ferror to let the 
user correct the input, edit-trivial-errors-p defaults to the value of 
*read-form-edit-trivial-errors-p*. The default value is t. 

If completion-alist is not nil, this function also sets up complete and c-? as 
input editor commands. When the user presses COMPLETE, the input editor 
tries to complete the current symbol over the set of possibilities defined by 
completion-alist. When the user presses c-?, the input editor displays the 
possible completions of the current symbol. 

The style of completion is the same as that offered by Zwei. completion-alist 
can be nil, an alist, an art-q-list array, or a keyword: 

nil No completion is offered. 

alist The car of each alist element is a string representing one 

possible completion. 

array Each element is a list whose car is a string representing 

one possible completion. The array must be sorted 
alphabetically on the cars of the elements. 

keyword If the symbol is :zmacs, completion is offered over the 
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definitions in Zmacs buffers. If the symbol is :flavors, 
completion is offered over all flavor names. 

The default for completion-alist is the value of 
*read-form-completion-alist*. The default value is :zmacs. 

completion-delimiters is nil or a list of characters that delimit "chunks" for 
completion. As in Zwei, completion works by matching initial substrings of 
"chunks" of text. If completion-delimiters is nil, the entire text of the 
current symbol is a single "chunk". The default is the value of 
♦read-form-completion-delimiters*. The default value is 
(#/- #/: #\space). 

*read-form-edit-trivial-errors-p* Variable 

If not nil, read-form checks for two kinds of errors. If a symbol is read, it 
checks whether the symbol is bound. If a list whose first element is a 
symbol is read, it checks whether the symbol has a function definition. If it 
finds an unbound symbol or undefined function, it offers to use a lookalike 
symbol in another package or calls parse-ferror to let the user correct the 
input. The default is t. 

*read-form-completion-alist* Variable 

If not nil, read-form sets up complete and c-? as input editor commands. 
When the user presses COMPLETE, the input editor tries to complete the 
current symbol over the set of possibilities defined by completion-alist. When 
the user presses c-?, the input editor displays the possible completions of the 
current symbol. 

The style of completion is the same as that offered by Zwei. 
♦read-form-completion-alist* can be nil, an alist, an art-q-list array, or a 
keyword: 

nil No completion is offered. 

alist The car of each alist element is a string representing one 

possible completion. 

array Each element is a list whose car is a string representing 

one possible completion. The array must be sorted 
alphabetically on the cars of the elements. 

keyword If the symbol is :zmacs, completion is offered over the 

definitions in Zmacs buffers. If the symbol is :flavors, 
completion is offered over all flavor names. 

The default value is :zmacs. 
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♦read-form-completion-delimiters* Variable 

The value is nil or a list of characters that delimit "chunks" for completion in 
read-form. As in Zwei, completion works by matching initial substrings of 
"chunks" of text. If *read-form-compietion-delimiters* is nil, the entire 
text of the current symbol is a single "chunk". The default value is 
(#/- #/: #\space). 

read-or-end &optional (stream standard-input) reader Function 

This function is like read-expression, except that if it is reading from an 
interactive stream and the user presses END as the first character or the first 
character after only whitespace characters, it returns two values, nil and 
tend. If it encounters any nonwhitespace characters, it calls the reader 
function with an argument of stream to read the input, reader defaults to 
read-expression, stream defaults to standard-input. 

The :expression-or-end and :eval-form-or-end options for 
prompt-and-read invoke read-or-end. 

This function is intended to read only from interactive streams. 

read-or-character &optional delimiters stream reader Function 

This function is like read-expression, except that if it is reading from an 
interactive stream and the user types one of the delimiters as the first 
character or the first character after only whitespace characters, it returns 
four values: nil, character, the character code of the delimiter, and any 
numeric argument to the delimiter. If it encounters any nonwhitespace 
characters, it calls the reader function with an argument of stream to read 
the input. 

delimiters is a character, a list of characters, or nil. The default is nil. 
reader defaults to read-expression, stream defaults to standard-input. 
This function is intended to read only from interactive streams. 

read-and-eval &optional stream (catch-errors t) Function 

This function calls read-expression to read a form, without completion. It 
then evaluates the form and returns the result. If catch-errors is not nil, it 
calls parse-ferror if an error occurs during the evaluation (but not the 
reading) so that the input editor catches the error. 

stream defaults to standard-input. This function is intended to read only 
from interactive streams. 

readline-no-echo &optional stream &key (terminators Function 

'(^return #\line #\end)) (full-rubout nil) 
(notification t) (prompt nil) (help nil) 
Reads a line of input from stream without echoing the input, and returns the 
input as a string, without the terminating character. This function is used 
to read passwords and encryption keys. It does not use the input editor but 
does allow input to be edited using RUBOUT. 
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stream must be interactive. It defaults to query-io. 
Following are the permissible keywords: 



: terminators 



:full-rubout 



:notification 



rprompt 



:help 



A list of characters that terminate the input. If the user 
types #\return, #\line, or #\end as a terminator, the 
function echoes a Newline. If the user types any other 
character as a terminator, the function echoes that 
character. The default is (#\return #\line #\end). 

If not nil and the user rubs out all characters on the line, 
the function returns nil. If nil and the user rubs out all 
characters on the line, the function waits for more input. 
The default is nil. 

If not nil and a notification is received, the function 
displays the notification and reprompts. If nil and a 
notification is received, the notification is ignored. The 
default is t. 

If nil, no prompt is displayed. Otherwise, the value should 
be a prompt option to be displayed at appropriate times. 
See the section "Displaying Prompts in the Input Editor", 
page 33. The default is nil. 

If not nil, the value should be a help option. See the 
section "Displaying Help Messages in the Input Editor", 
page 34. Then, when the user presses HELP, the function 
displays the help option and reprompts. If nil and the 
user presses HELP, the function just returns #\help. The 
default is nil. 
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3. Messages for Input From Interactive Streams 



All interactive streams support these input operations. Some streams have 
specialized versions of some operations, partly because different kinds of streams have 
different sources of input when input is to come from the stream instead of the 
input buffer. Windows, for example, take input from an I/O buffer. See the section 
"Messages for Input From Windows", page 134. 

:any-tyi &optional eof-action of smnteractive-stream Method 

Read and return the next character of input from the stream, waiting if 
there is none, Where the character comes from depends on the value of the 
variable rubout-handler. Following is a summary of actions for each 
possible value of rubout-handler: 

nil If the input buffer contains unscanned input, take the 

next character from there. Otherwise, take the next 
character from the stream. 

:read If the input buffer contains unscanned input, take the 

next character from there. Otherwise, if an activation blip 
or character is present, return that. Otherwise, enter the 
input editor. 

:tyi Take the next character from the stream. 

If eof-action is not nil, an error is signalled when an end-of-file is 
encountered. Otherwise, the method returns nil when an end-of-file is 
encountered. The default for eof-action is nil. 

:any-tyi-no-hang &optional eof-action of smnteractive-stream Method 

Return the next character from the stream if it is immediately available. If 
no characters are immediately available, return nil. It is an error to call this 
method from inside the input editor (that is, if the value of rubout-handler 
is not nil), eof-action is ignored. This is used by programs that continuously 
do something until a key is typed, then look at the key and decide what to 
do next. 

:tyi &optional eof-action of smnteractive-stream Method 

If called from outside the input editor, this is the same as :any-tyi, except 
that only integers and nil can be returned. Blips are discarded, unless the 
first element of the blip is :mouse-button and the second element is 
#\mouse-r-l; in this case, the method pops up a system menu. If called 
from inside the input editor with :full-rubout specified and if an activation 
blip is read when the input buffer is empty, the method causes control to be 
returned from the input editor. 
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:tyi-no-hang &optional eof-action of sirinteractive-stream Method 

This is like rany-tyi-no-hang, except that only integers and nil can be 
returned. Blips are discarded, unless the first element of the blip is 
rmouse-button and the second element is #\mouse-r-l; in this case, the 
method pops up a system menu. 

:list-tyi of sirinteractive-stream Method 

This is like :any-tyi except that it only returns blips and never returns 
integers. If it encounters any integers in the input stream, it discards them 
entirely (they are removed from the stream and the program never sees 
them). 

runtyi ch of si:interactive-stream Method 

Return ch to the input buffer or the stream so that it will be the next 
character returned by :any-tyi or :tyi. ch must be the last character that 
was rtyi'ed, and it is illegal to do two runtyi's in a row. Where ch is put 
depends on the value of the variable rubout-handler. Following is a 
summary of actions for each possible value of rubout-handler: 

nil If the input buffer contains scanned input, decrement the 

scan pointer. Otherwise, give ch back to the stream. 

:read Decrement the input editor scan pointer. 

:tyi Give ch back to the stream. 

This method is used by parsers that look ahead one character, such as read. 

rlisten of si:interactive-stream Method 

Return t if there are any characters available to :any-tyi or :tyi, or nil if 
there are not. For example, the editor uses this to defer redisplay until it 
has caught up with all of the characters that have been typed in. 

:clear-input of si:interactive-stream Method 

Clear the input buffer and any input buffered by the stream. This flushes 
all the characters that have been typed at this stream, but have not yet been 
read. 

:line-in &optional leader of sirinteractive-stream Method 

Reads characters from the stream and returns them as a string. If called 
from outside the input editor, reads characters until a #\return, #\line, or 
#\end activation character is encountered. If called from inside the input 
editor, reads characters until a #\return delimiter is encountered. The 
activation or delimiter character is not part of the returned string. 

The method returns two values: the string and an eof flag. If the stream 
reaches end-of-file while reading characters, it returns the characters read as 
a string and returns a second value of t. Otherwise, the second returned 
value is nil. 
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If leader is an integer, the returned string has an array leader of length 
leader, and the fill pointer is set to the location in the string following the 
last one read. Otherwise, the string has no array leader. 

Example: 

This feature is useful for debugging programs that read from noninteractive 
streams. For example, the following function reads a single line-oriented 
record, in which the first line is a decimal number saying how many lines are 
in the rest of the record. 

(defun read-record (&optiona1 (stream standard-input)) 
(loop repeat (parse-number (send stream : line-in) nil 10.) 
collect (send stream :line-in))) 

If this function is invoked on an interactive stream, the input editor is 
enabled automatically each time the :line-in message is sent, but it is not 
possible to edit across line boundaries. For example, once the number of lines 
in the record is typed, it isn't possible to change it. 

(defun read-record (&optional (stream standard-input)) 
(with-input-editing (stream) 
(loop repeat (parse-number (send stream : line-in) nil 10.) 
collect (send stream : line-in)))) 

Wrapping a with-input-editing form around the body establishes a single 
input editing context for each record, with-input-editing has no effect 
when stream is a noninteractive stream, so this same function may used for 
reading from a file or reading from an interactive stream. 

:string-in eof string &optional (start 0) end of Method 

si:interactive-stream 

Reads characters from the stream into stringy using the substring delimited 
by start and end. start defaults to 0, and end defaults to the length of the 
string. 

eof specifies stopping actions: 

Value Action 

nil Reading characters into the string stops either when it has 

transferred the specified character count or when end-of- 
file is reached, whichever comes first. For a string with a 
fill pointer, sets the fill pointer to the location one greater 
than the last location into which a character was stored. 

not nil If end-of-file is encountered while trying to transfer a 

specific number of characters, signals sys:end-of-file, with 
the value of eof as the report string. If eof is t, a default 
report string is used. 
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The method returns two values. The first is the location in the string that 
is one greater than the last one into which a character was stored. The 
second value is t if end-of-file was reached, nil otherwise. 

:string-line-in eof string &optional (start 0) end of Method 

sirinteractive-stream 
:string-line-in is a combination of :string-in and :line-in. It reads a line of 
characters from the stream into stringy using the substring delimited by start 
and end. start defaults to and end to the length of string. If called from 
outside the input editor, reads characters until a #\return, #\line, or 
#\end activation character is encountered. If called from inside the input 
editor, reads characters until a #\return delimiter is encountered. The 
activation or delimiter character is not stored into string. 

eof specifies stopping actions: 

Value Action 

nil Reading characters into the string stops when a delimiter 

is encountered, when the string is full, or when end-of-file 
is reached, whichever comes first. For a string with a fill 
pointer, sets the fill pointer to the location one greater 
than the last location into which a character was stored. 

not nil If end-of-file is encountered, signals sys:end-of-file, with 

the value of eof as the report string. If eof is t, a default 
report string is used. 

The method returns three values: 

• The location in string that is one greater than the last location into 
which a character was stored. 

• t if end-of-file was reached, nil otherwise. 

• nil if the entire contents of the line fit into the string or end-of-file 
was reached, otherwise t. If this value is t, as much of the line as 
possible was stored into the string and more is waiting to be read. 

If the second and third values are both nil, a delimiter was read. If either is 
t, no delimiter was read. 
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4. Intercepted Characters 



Interactive streams specially intercept some characters. Some are intercepted when 
some user process is about to read the character from a stream; others are 
intercepted as soon as they are typed. This section describes the first kind of 
interception. For information on asynchronously intercepted characters: See the 
section "Asynchronous Characters", page 139. See the section "Interactive-stream 
Operations for Asynchronous Characters", page 17. 

The value of the variable sysrkbd-intercepted-characters is a list of characters 
that are intercepted and not returned as input from the stream. These characters 
default to #\abort, #\m-abort, #\suspend, and #\m-suspend. Following are 
the standard actions to be taken when these characters are intercepted: 

#\abort Signal sys:abort 

#\m-abort Reset the current process 

#\suspend Call the break function 

#\m-suspend Break to the Debugger 

By convention, programs are all expected to use the ABORT key as a command to 
abort things in some appropriate sense for that program. If you don't do anything 
special, ABORT is intercepted automatically. Most interactive programs just set up 
restart handlers for sysrabort. But some programs may want to do something 
specific when the user presses ABORT (or SUSPEND). 

You can replace the system default action by binding the variable 
sys:kbd-intercepted-characters. By default, this variable is bound to the value of 
sysrkbd-standard-intercepted-characters. If you want the system to intercept 
only the standard abort characters, you can bind this variable to the value of 
sys:kbd-standard-abort-characters. If you want the system to intercept only the 
standard break characters, you can bind this variable to the value of 
sys:kbd-standard-suspend-characters. 

sysrkbd-intercepted-characters Variable 

The value is a list of characters that are intercepted when they are read 
from an interactive stream. 

Bind this variable when you want to change the characters that the system 
intercepts. The default value is the value of 
sys:kbd-standard-intercepted-characters: 
(#\abort #\m-abort #\suspend #\m-suspend). 
sysrkbd-intercepted-characters is reset to this value on warm booting. 
You can bind sysrkbd-intercepted-characters to any subset of the default 
value, but you cannot include any characters that are not members of the 
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default value. If you want the system to intercept only the standard abort 
characters, bind sysrkbd-intercepted-characters to the value of 
sys:kbd-standard-abort-characters. If you want the system to intercept 
only the standard break characters, bind sys:kbd-intercepted-characters 
to the value of sysrkbd-standard-suspend-characters. 

sysrkbd-standard-intercepted-characters Variable 

The value is a list of characters that is the default value of 
sysrkbd-intercepted-characters. The default value is 
(#\abort #\m-abort #\suspend #\m-suspend). This is a constant. If 
you want to change the characters that the system intercepts, bind 
sysrkbd-intercepted-characters, not 
sys:kbd-standard-intercepted-characters. 

sys:kbd-standard-abort-characters Variable 

The value is a list of characters that are the default abort characters 
intercepted by the system. The default value is (#\abort #\m-abort). 
This is a constant. If you want the system to intercept only the standard 
abort characters, bind sysrkbd-intercepted-characters to the value of 
sys:kbd-standard-abort-characters. 

sys:kbd-standard-suspend-characters Variable 

The value is a list of characters that are the default suspend characters 
intercepted by the system. The default value is 

(#\suspend #\m-suspend). This is a constant. If you want the system to 
intercept only the standard suspend characters, bind 
sysrkbd-intercepted-characters to the value of 
sysrkbd-standard-suspend-characters. 
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5. Interactive-stream Operations for Asynchronous 
Characters 



The keyboard process intercepts some characters as soon as they are typed: See the 
section "Asynchronous Characters", page 139. All interactive streams maintain a list 
of characters to be handled asynchronously. Remote terminals, however, do not 
handle asynchronous characters. 

You can set up your own handling of asynchronous characters by using the 
:asynchronous-character-p, :handle-asynchronous-character, 
:add-asynchronous-character, and :remove-asynchronous-character messages 
and the :asynchronous-characters init option for si:interactive-stream. 

tasynchronous-characters spec-list (for sitinteractive-stream) Init Option 

Specifies the asynchronous characters for the stream, spec-plist is a list of 
specs, each of which is a list containing a character name and a function 
spec. The following default asynchronous characters are defined for 
si:interactive-stream: 

( :default-init-plist 
: asynchronous-characters 

*((#\c-abort tv:kbd-asynchronous-intercept-character) 
( #\c-m-abort tv : kbd-asynchronous- i ntercept-character ) 
( #\c-suspend tv : kbd-asynchronous- i ntercept-character ) 
( #\c-m-suspend tv: kbd-asynchronous- i ntercept-character ) ) ) 

:asynchronous-character-p character of si:interactive-stream Method 

Returns non-null when character is an asynchronous character for this 
stream. 

:handle-asynchronous-character character of Method 

si:interactive-stream 

Finds the function associated with character in the asynchronous characters 
list. It calls the function with two arguments, character and self. This is 
mainly for use by the Keyboard Process although user processes can use it 
also. 

:add-asynchronous-character character handler of Method 

si:interactive-stream 

Defines a new asynchronous character for the stream, character is the 
character to be treated asynchronously and handler is the function to be 
called (with two arguments, character and self). It checks the types of the 
arguments. 
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:remove-asynchronous-character character of Method 

si:interactive-stream 

Removes an asynchronous character from the list for the stream. 
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6. Interactive Streams and Mouse-sensitive Items 



Some windows support mouse sensitivity. They can display representations of items 
in such a way that moving the mouse onto the item causes it to be highlighted, and 
clicking the mouse on the item does something with the item. One example is the 
basic mouse-sensitive items facility: See the section "The Mouse-sensitive Items 
Facility", page 279. 

The fundamental message that creates and displays a mouse-sensitive item is :item. 
All interactive streams support this message, whether or not they support mouse 
sensitivity. If they do not support mouse sensitivity, they just display a printed 
representation of the item. 

Any interactive stream can also display an ordered list of items, using the function 
si:display-item-list. This displays each item by sending an :item message to the 
stream. 

:item type item &rest formot-args of si:interactive-stream Method 

Creates and displays a (possibly mouse-sensitive) item of type type on the 
stream. If the stream does not support mouse-sensitivity, this just ignores 
type and displays item on the stream. If format-args are supplied, they are a 
format control string and control args to be used to display the item. 
Otherwise, the item is displayed by calling princ with a first argument of 
item. 

si:display-item-list stream type list &optional item-string Function 

(order-columnwise t) 
Displays a list of items on stream in evenly spaced columns, stream must be 
interactive. If it supports mouse sensitivity, the items displayed are also 
made mouse sensitive. 

list is a list of items to be displayed. Each item in the list is displayed by 
sending the stream an :item message with type as the first argument. If 
the item is not itself a list, the item is the second argument to the :item 
message. 

If the item to be displayed is a list, the arguments to the :item message 
depend on item-string. If item-string is not nil, the second argument to the 
:item message is the first element of the item. If item-string is nil, the item 
should be an alist whose car is a string to be displayed and whose cdr is the 
item itself. In this case, the second argument to the :item message is the 
cdr of the item, the third argument is " - A", and the fourth argument is the 
car of the item. The default for item-string is nil. 

If order-columnwise is not nil, the items are ordered down columns. If 
order-columnwise is nil, the items are ordered across rows. The default is t. 
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7. The Input Editor Program Interface 



7.1 How the Input Editor Works 

The input editor is a feature of all interactive streams, that is, streams that connect 
to terminals. Its purpose is to let you edit minor mistakes in typein. At the same 
time, it is not supposed to get in the way; Lisp is to see the input as soon as you 
have typed a syntactically complete form. The definition of "syntactically complete 
form" depends on the function that is reading from the stream; for read, it is a 
Lisp expression. This section describes the general protocol used for communication 
between the input editor and reading functions such as read and readline. 

By reading function we mean a function that reads a number of characters from a 
stream and translates them into an object. For example, read reads a Lisp 
expression and returns an object, readline reads a line of characters and returns a 
string as its first value. Reading functions do not include the more primitive :tyi 
and :any-tyi stream operations, which take and return one character or blip from 
the stream. 

The tricky thing about the input editor is the need for it to figure out when you are 
all done. The idea of an input editor is that as you type in characters, the input 
editor saves them up in an input buffer so that if you change your mind, you can 
edit them and replace them with different characters. However, at some point the 
input editor has to decide that the time has come to stop putting characters into the 
input buffer and let the reading function start processing the characters. This is 
called "activating". 

The right time to activate depends on the function calling the input editor, and 
determining it may be very complicated. If the function is read, figuring out when 
one Lisp expression has been typed requires knowledge of all the various printed 
representations, what all currently defined reader macros do, and so on. The input 
editor should not have to know how to parse the characters in the input buffer to 
figure out what the caller is reading and when to activate; only the caller should 
have to know this. The input editor interface is organized so that the calling 
function can do all the parsing, while the input editor does all the handling of 
editing commands, and the two are kept completely separate. 

Following is a summary of how the input editor works. The input editor used to be 
called the rubout handler, and some operations and variables still have "rubout- 
handler" in their names. 

When a reading function is called to read from a stream that supports the 
:input-editor operation, that function "enters" the input editor. It then goes ahead 
:tyi'ing characters from the stream. Because control is inside the input editor, the 
stream echoes these characters so the user can see the input. (Normally echoing is 
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considered to be a higher-level function outside of the province of streams, but when 
the higher-level function tells the stream to enter the input editor it is also handing 
it the responsibility for echoing). The input editor is also saving all these characters 
in the input buffer, for reasons disclosed in the following paragraph. When the 
reading function decides it has enough input, it returns and control "leaves" the 
input editor. That was the easy case. 

If you press RUBOUT or a keystroke that represents another editing command, the 
input editor processes the command and lets you insert characters before the last 
one in the line. The input editor modifies the input buffer and the screen 
accordingly. Then, when you type the next nonediting character at the end of the 
line, a throw is done, out of all recursive levels of read, reader macros, and so 
forth, back to the point where the input editor was entered. Now the read is tried 
over again, rereading all the characters you had typed and not rubbed out, but not 
echoing them this time. When the saved characters have been exhausted, additional 
input is read from you in the usual fashion. 

The input editor has options that can cause the throw to occur at other times as 
well. With the ractivation option, when you type an activation character a throw 
occurs, a rescan is done if necessary, and a final blip is returned to the reading 
function. With the zpreemptable and :command options, a blip or special 
character in the input stream causes control to be returned from the input editor 
immediately, without a rescan. These options let you process mouse clicks or special 
keystroke commands as soon as they are read. 

The effect of all this is a complete separation of the functions of input editing and 
parsing, while at the same time mingling the execution of these two functions in 
such a way that input is always "activated" at just the right time. It does mean 
that the parsing function (in the usual case, read and all macro-character 
definitions) must be prepared to be thrown through at any time and should not 
have nontrivial side-effects, since it may be called multiple times. 

If an error occurs while inside the input editor, the error message is printed and 
then additional characters are read. When you press RUBOUT, it rubs out the error 
message as well as the last character. You can then proceed to type the corrected 
expression; the input is reparsed from the beginning in the usual fashion. 



7.2 Invoking the Input Editor 

The variable rubout-handler indicates the current state of input editing. This 
variable is not nil if the current process is already inside the input editor. 

rubout-handler Variable 

Indicates the status of input editing within a process. 

This variable is used internally by the tinput-editor method and the input 
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editor. It should not be necessary for user programs to examine its value 
since the with-input-editing special form is provided for this purpose. 

The possible values for this variable are: 

Value Meaning 

nil The process is outside the input editor. 

tread The process is inside the :input-editor method. 

:tyi The process is inside the editing portion of the :tyi 

method. 

The input editor is invoked on a stream when the stream receives an rinput-editor 
message. The rinput-editor and :tyi methods of si:interactive-stream contain 
the code of the input editor. The rinput-editor method initializes the input editor, 
establishes its catch, and then calls back to the reading function with 
rubout-handler bound to :read. When the reading function sends the :tyi or 
:any-tyi message, input is taken from the input buffer. If no input is available, the 
editing or :tyi portion of the input editor is invoked, and rubout-handler is bound 
to :tyi. 

The first argument to the :input-editor message is the function that the input 
editor should call to do the reading, and the rest of the arguments are passed to 
that function. If the reading function returns normally, the values returned by the 
:input-editor message are just those returned by the reading function. If the input 
editor returns by throwing out of the reading function, the return values depend on 
which option caused the input editor to throw: See the option :full-rubout, page 
27. See the option rpreemptable, page 31. See the option rcommand, page 32. 

The input editor can take a series of options. These are specified dynamically by the 
special forms with-input-editing-options and with-input-editing-options-if. For 

a description of the options: See the section "Input Editor Options", page 27. 

with-input-editing-options options &body body Special Form 

Specifies input editing options and executes body with those options in effect. 
The scope of the option specifications is dynamic. 

options is a list of input editor option specifications. Each element is a list 
whose car is an option-name specification and whose cdr is a list of forms to 
be evaluated to yield "arguments" for the option. The option-name 
specification is a keyword symbol or a list whose car is a keyword symbol. 
The symbol is the name of the option. 

If the option-name specification is a list and if the symbol roverride is an 
element of the cdr of the list, this option specification overrides any higher- 
level specifications for this option. Otherwise, the specification for each option 
that is dynamically outermost (that is, the specification from the highest-level 
caller) is in effect during the execution of body. 
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with-input-editing-options returns whatever values body returns. 

In the following example, the user is prompted for a Lisp expression. Two 
input editor options are specified. The first says that the caller is also willing 
to receive mouse or menu blips. The second specifies a prompt. 



(with-input-editing-options ((.-preemptable :blip) 

(-.prompt "Form: ")) 



(read)) 

In the following example, the user is prompted for a line of text. The text 
may be activated by any of the characters RETURN, END, or TRIANGLE. This 
might be useful if activating with triangle meant something different from 
activating with RETURN. This example also demonstrates the use of toverride 
to make this motivation specification override any higher-level motivation 
specifications. 

(with-input-editing-options 

((( ractivation roverride) 'mernq *(#\return #\end #\triangle))) 
(prompt-and-read .-string "Name: ")) 

For a list of input editor options: See the section "Input Editor Options", 
page 27. See the special form with-input-editing-options-if, page 24. 

with-input-editing-options-if cond options &body body Special Form 

Executes body, possibly with specified input editing options in effect. The 
scope of the option specifications is dynamic. 

cond is a form to be evaluated at run-time. If cond returns non-nil, the 
specified input editor options are in effect during the execution of body. 

options is a list of input editor option specifications. Each element is a list 
whose car is an option-name specification and whose cdr is a list of forms to 
be evaluated to yield "arguments" for the option. The option-name 
specification is a keyword symbol or a list whose car is a keyword symbol. 
The symbol is the name of the option. 

If the option-name specification is a list and if the symbol roverride is an 
element of the cdr of the list, this option specification overrides any higher- 
level specifications for this option. Otherwise, the specification for each option 
that is dynamically outermost (that is, the specification from the highest-level 
caller) is in effect during the execution of body. 

with-input-editing-options-if returns whatever values body returns. 

For a list of input editor options: See the section "Input Editor Options", 
page 27. See the special form with-input-editing-options, page 23. 

This example illustrates the use of the rcommand, rpreemptable, and :prompt 
input editor options. It is a simple command loop that reads different kinds of 
commands - typed Lisp expressions, single-keystroke commands, and mouse clicks. 
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The Lisp expressions are read using the read-or-end function. You can provide 
four kinds of input: 

Input Action 

END Exit the command loop 

Lisp form Print form on next line 

Mouse click Display type of click and mouse coordinates 

Single-key command Display keystroke 

The predicate for detecting a single-keystroke command simply checks for the Super 
bit. In a more complex program, it might look up the character in a command 
table. 

(defun command-char-p (c) (char-bit c :super)) 

(defun command- loop () 
(loop 
do (multiple-value-bind (value flag) 
(with- input-editing-options 
((:command 'command-char-p) 
( tpreemptable tblip) 
(: prompt "Command loop input: ")) 
(read-or-end)) 
(selectq flag 
( :end 
(format t "Done") 
(return t)) 
(:blip 
(selectq (car value) 
( :mouse-button 

(destructuring-bind (click nil x y) (cdr value) 
(format t "~C click at ~D, ~D" click x y))) 

(otherwise (format t "Random blip S" value)))) 

( : command 

(format t "Execute ~:C command" (second value))) 
(otherwise 
(format t "~&Value is ~S" value)))))) 

To write a reading function that invokes the input editor, you should use the 
with-input-editing special form instead of sending the :input-editor message 
directly. Such functions as read and readline use this special form to provide input 
editing. 

with-input-editing (&optional stream keyword) &body body Special Form 

This special form provides a convenient way of invoking the input editor for 
use by a reading function. It establishes a context in which input editing 
should be provided. Use with-input-editing instead of sending an 
dnput-editor message directly. 
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Both "arguments" are optional, stream is the stream from which characters 
are read; if stream is not provided or is nil, standard-input is used. 

keyword determines the activation characters for the input editor: 

Value Activation characters 

nil None (unless specified at a higher level). This is the 

default. 

:end-activation #\end 

:line-activation #\end, #\return, and #\line 

:line #\end, #\return, and #\line. In addition, a Newline is 

echoed after the reading function returns. 

To supply other input editor options: See the special form 
with-input-editing-options, page 23. See the special form 
with-input-editing-options-if, page 24. 

with-input-editing defines an internal lexical closure with body as its body. 
When the with-input-editing form is evaluated from outside the input 
editor, the stream is sent an rinput-editor message if it handles it. The 
argument to the :input-editor message is the lexical closure, except that if 
the :line keyword is supplied, with-input-editing also arranges to echo a 
Newline after the lexical closure returns. If the with-input-editing form is 
evaluated from inside the input editor or if the stream does not handle the 
rinput-editor message, the lexical closure is called instead. 

with-input-editing returns whatever values body returns. 

The following example defines a simple sentence parser. 
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(defun read-sentence (Soptional (stream standard-input)) 
(with-input-editing-options ((rprompt "Type a sentence: ")) 
(with-input-editing (stream) 
(loop named sentence 

with sentence = nil 

for word = (make-array 20. :type art-string :fill-pointer 0) 
do (loop for char = (send stream :tyi) 
do 
(cond ((memq char *(#\space #\return #/. #/? #/,)) 
(if (not (equal word "")) 
(push word sentence)) 
(selectq char 
((#\space #\return #/,) 
(return)) 
(#\. 
(push rperiod sentence) 
(return-from sentence (nreverse sentence))) 
(#\? 
(push :question-mark sentence) 
(return-from sentence (nreverse sentence))))) 
(t (array-push-extend word char)))))))) 



7.3 Input Editor Options 

The input editor can take a series of options, specified by the special forms 
with-input-editing-options and with-input-editing-options-if. Following are 
descriptions of the options. 

:full-rubout token Option 

If the user rubs out all the characters that were typed, control is returned 
from the input editor immediately. Two values are returned: nil and token. 
If the user doesn't rub out all the characters, the input editor propagates 
multiple values back from the function that it calls, as usual. In the absence 
of this option, the input editor simply waits for more characters to be typed 
and ignores any additional rubouts. 

:pass-through &rest characters Option 

The characters in characters are not to be treated as special by the input 
editor. This option is used to pass format effectors (such as HELP or 
CLEAR- INPUT) through to the reading function instead of interpreting them as 
input editor commands. :pass-through is allowed only for characters with 
no modifier bits set, that is, for character codes through 377 (octal). For 
characters that have modifier bits set and must be visible to the reading 
function, use :do-not-echo or motivation 
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rprompt &rest prompt-option Option 

When it is time for the user to be prompted, the input editor displays 
prompt-option, prompt-option can have one element, which can be nil, a 
string, a function, or a symbol other than nil; or it can have more than one 
element: See the section "Displaying Prompts in the Input Editor", page 33. 

The difference between :prompt and :reprompt is that the latter does not 
display the prompt when the input editor is first entered, but only when the 
input is redisplayed (for example, after a screen clear). If both options are 
specified, rreprompt overrides :prompt except when the input editor is first 
entered. 

:reprompt &rest prompt-option Option 

When it is time for the user to be reprompted, the input editor displays 
prompt-option, prompt-option can have one element, which can be nil, a 
string, a function, or a symbol other than nil; or it can have more than one 
element: See the section "Displaying Prompts in the Input Editor", page 33. 

Unlike :prompt, :reprompt displays the prompt only when input is 
redisplayed (for example, after a screen clear), not when the input editor is 
first entered. If both rprompt and rreprompt are specified, zreprompt 
overrides :prompt except when the input editor is first entered. 

:complete-help &rest help-option Option 

When the user presses help, the input editor types out a message determined 
by help-option. None of the standard input editor help is displayed. If a 
:brief-help option has been specified, it overrides :complete-help. 
:complete-help overrides :merged-help and :partial-help. 

help-option can have one element, which can be a string, a function, or a 
symbol; or it can have more than one element. For an explanation: See the 
section "Displaying Help Messages in the Input Editor", page 34. 

This option is intended for programs that supply their own input editor help 
messages. 

:partial-help &rest help-option Option 

When the user presses HELP, the input editor first types out a message 
determined by help-option. It then types out a message describing how to 
invoke input editor commands and other information about the stream. If a 
:brief-help, :complete-help, or :merged-help option has been specified, it 
overrides :partial-help. 

help-option can have one element, which can be a string, a function, or a 
symbol; or it can have more than one element. For an explanation: See the 
section "Displaying Help Messages in the Input Editor", page 34. 

This option is intended for use when inexperienced users might be typing to 
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the input editor. Often help-option gives some information about which 
program the user is typing to and what the user can do to exit from it. 

:merged-help function &rest arguments Option 

When the user presses help, the input editor types out a message determined 
by the arguments, function is a function that takes at least two arguments. 
The input editor calls the function to print the help message. The first 
argument is the stream. The second argument is a continuation (a list) to 
print a standard message describing how to invoke input editor commands 
and other information about the stream. When the function wants to print 
this message, it should apply the car of the continuation to the cdr. If any 
arguments are supplied, they are the remaining arguments to the function. 

If a :brief-help or :complete-help option has been specified, it overrides 
:merged-help. :merged-help overrides :partial-help. 

This option is intended for programs that want to decide when and where to 
display their own help messages and the standard help message. 

:brief-help &rest help-option Option 

When the user presses HELP, the input editor displays a message determined 
by help-option on the same line as the typein. The message is displayed in 
the default typeout font, and none of the usual conventions about input 
editor typeout apply. :brief-help overrides :complete-help, :merged-help, 
and :partial-help. 

help-option can have one element, which can be a string, a function, or a 
symbol; or it can have more than one element. For an explanation: See the 
section "Displaying Help Messages in the Input Editor", page 34. 

This option is intended for programs like fquery that need to supply only a 
brief help message, usually about expected typein. 

rfnitial-input string &optional begin end cursor-position Option 

When the input editor is entered, string is inserted into the input buffer as if 
the user had typed it. The user can edit the string before activating, begin 
and end are indices into string and mark the portion of the string to be 
copied into the input buffer, begin defaults to 0; end defaults to 
(array-active-length string), cursor-position is an index into the string 
where the cursor should initially be placed. The default is to place the cursor 
at the end of the portion of the string copied into the input buffer, string 
can be nil, which is the same as not specifying the option. 

In the following example, the user is prompted for a line of text. The input 
buffer initially contains the name of the user, and the cursor is placed at the 
beginning of the input buffer. 
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(with-input-edi ting-options 

(( rinitial-input fs: user-personal -name nil nil 0)) 
(prompt-and-read :string "Full name: ")) 

Placing a string in the input buffer is one style of input defaulting. Another 
style leaves the input buffer empty but allows a default to be yanked with 
c-n-Y. See the option :input-history-default, page 30. 

rinput-history-default string Option 

Specifies string as the default to be yanked by c-n-Y. string is temporarily 
placed at the head of the input history. If the user types c-n-Y n-Y, the 
true first element of the input history is yanked. c-n-e c-n-Y shows string 
at the head of the input history, and the entries in the input history are 
shifted down by one. 

In the following example, the user is prompted for a line of text. The input 
buffer is initially empty, but the c-n-Y command yanks a default, which is 
the name of the user. 

(with- input-editing-options 

(( : input-history-default fs: user-personal -name)) 
(prompt-and-read :string "Full name: ")) 

This option is used by the :pathname option for prompt-and-read 

rblip-handler function Option 

Specifies a function to handle blips received while inside the input editor. 
function must be a function of two arguments. The first argument is the 
blip; the second argument is the stream that received the blip. The handler 
is invoked when the input editor receives a blip. If the handler returns 
non-nil, no further action is taken. If it returns nil and a rpreemp table 
option is in effect, the actions specified by that option are taken. Otherwise, 
the default blip handler is invoked. 

In the following example, the user is prompted for a line of text. While 
entering this text, the user may also click the left or middle mouse buttons. 
If the left mouse button is clicked, the coordinates of the mouse with respect 
to the window are inserted into the input buffer. If the middle button is 
clicked, the name of the window is inserted. 

(defun example-blip-handler (blip ignore) 
(destructuring-bind (type click window x y) blip 
(and (eq type : mouse-button) 
(selectq click 
(#\mouse-l-1 
(si :ie-insert-string (format nil " ~D ~D" x y)) 
t) 

(#\mouse-m-1 
(si :ie-insert-string (format nil " ~A" window)) 
t))))) 
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(with-input-editing-options (( : blip-handler 'example-blip-handler)) 
(prompt-and-read :string "Blip handler test: ")) 

si:ie-insert-string is an internal function for inserting a string into the 
input buffer. Since the language for writing input editor commands has not 
been formalized, this example might not work in a later release. 

:do-not-echo &rest characters Option 

The characters in characters are interpreted as activation characters and are 
not echoed. The comparison is done with char=, not char-equal, so that 
the control and meta bits are not masked off. The characters are not 
inserted into the input buffer and are not interpreted as input editor 
commands. When one of these characters is typed, the final :tyi value 
returned is the character, not a blip. 

This option exists only for compatibility with earlier releases. New programs 
should use the motivation option. 

motivation function &rest arguments Option 

For each character typed, the input editor invokes function with the 
character as the first argument and arguments as the remaining arguments. 
If the function returns nil, the input editor processes the character as it 
normally would. Otherwise, the cursor is moved to the end of the input 
buffer, a rescan of the input is forced (if one is pending), and the blip 
(motivation character numeric-arg) is returned by the final sending of the 
:any-tyi message to the stream. Activation characters are not inserted into 
the input buffer, nor are they echoed by the input editor. It is the 
responsibility of the reading function to do any echoing. For instance, 
readline, not the input editor, types a Newline at the end of the input 
buffer when RETURN, END, or LINE is pressed. 

:preemptable token Option 

A blip in the input stream causes control to be returned from the input 
editor immediately. Two values are returned: the blip and token y which is 
usually a keyword symbol. Any unscanned input typed before the blip 
remains in the input buffer, available to the next read operation from the 
stream. 

:no-input-save Option 

The input editor does not save the scanned contents of the input buffer on 
the input history when returning from the reading function. This is 
intended for use by functions such as fquery that use the input editor to 
ask simple questions whose responses are not worth saving, yes-or-no-p 
uses :no-input-save by default. 
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rcommand function &rest arguments Option 

This option is used to implement nonediting single-keystroke commands. For 
each character typed, the input editor invokes function with the character as 
the first argument and arguments as the remaining arguments. If the 
function returns nil, the input editor processes the character as it normally 
would. Otherwise, control is returned from the input editor immediately. 
Two values are returned: a blip of the form (.'command character 
numeric-arg) and the keyword :command. Any unscanned input typed 
before the command character remains in the input buffer, available to the 
next read operation from the stream. 

reditor-command &rest command-alist Option 

This option lets you specify your own input editor editing commands. Each 
element of command-alist is a cons whose car is a character and whose cdr is 
a symbol or a list. If the cdr is a symbol, it is a function to be called with 
no arguments when the user types the associated character. If the cdr is a 
list, the car of the list is a function to be applied to the cdr of the list when 
the user types the associated character. The function can examine the 
internal special variables that describe the state of the input editor. 

If :editor-command specifies a command that is invoked by the same 
character as one of the standard input editor editing commands, the 
command specified by :editor-command overrides the standard command. 

:input-wait &optional whostate function &rest arguments Option 

When the input editor waits for input, it sends the stream an :input-wait 
message with the arguments to the :input-wait option as arguments. In 
addition, unless the rsuppress-notifications option has been specified, 
:input-wait returns when a notification is received. See the message 
:input-wait in Reference Guide to Streams, Files, and I/O. 

:input-wait-handler function &rest arguments Option 

When the input editor is waiting for input it sends the stream an 
:input-wait message. After :input-wait returns, the input editor applies 
function to arguments. The input editor does not process the input or 
display the notification until function returns. 

rsuppress-notifications flag Option 

If flag is not nil, notifications received while in the input editor are ignored. 

:notification-handler function &rest arguments Option 

If a notification is received while in the input editor, function is called to 
handle it. function should take at least one argument, the notification (as 
returned by the rreceive-notification message to the stream), arguments 
are the remaining arguments to function, function can do anything it wants 
with the notification. To display the notification, function would usually call 
sys:display-notification. 
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If this option is not specified, notifications appear one after the other using 
:insert-style typeout. 

Following are two simple examples of notification handlers. The first handler 
assumes that you want each notification to overwrite the previous one. The 
second handler assumes that you want them to appear one after another. 
♦window* should be bound to a window and *stream* to a stream where 
you want the notifications to appear. 

(defun my-notification-handler-1 (notification) 
(send *window* : clear-window) 
(sys:display-notification *window* notification :window)) 

(defun my-notification-handler-2 (notification) 

(sysrdisplay-notification *stream* notification :stream)) 



7.4 Displaying Prompts in the Input Editor 

The input editor options rprompt and rreprompt and the functions 
readline-no-echo and sys:read-character take prompt arguments that let you 
specify an input editor prompt, prompt can be nil, a string, a function, a symbol 
other than nil, or a list (for the input editor options, the list is an &rest argument): 

nil No prompt is displayed. 

string A format control string to be passed to format with one 

argument, the stream on which the prompt is displayed. 

function or symbol other than nil 

A function to display the prompt. The function should take two 
arguments: the first is the stream on which the prompt is 
displayed, and the second is a keyword that indicates the origin of 
the function call. 

list If the first element is nil, no prompt is displayed. If the first 

element is a string, it is a format control string to be passed to 
format with the remaining elements of the list as arguments. If 
the first element is a function or a symbol other than nil, it is a 
function to display the prompt. The first argument to the 
function is the stream on which the prompt is displayed. The 
second argument is a keyword that indicates the origin of the 
function call. The remaining arguments are the remaining 
elements of the list. 

When a function is called to display the prompt, the second argument to the 
function is a keyword that indicates the origin of the function call: 
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Keyword 
rprompt 



Function called from 

rinput-editor method of si:interactive-stream, when the input 
editor is entered 



rrestore :restore-input-buffer method of sirinteractive-stream 

tfinish-typeout :finish-typeout method of sirinteractive-stream 

rrefresh Body of the input editor, when the user presses REFRESH 

rerase-typeout Body of the input editor, when the user presses PAGE 

7.5 Displaying Help Messages in the Input Editor 



The input editor options :brief-help, :partial-help, and :complete-help and the 
functions readline-no-echo and sysrread-character take help arguments that let 
you specify input editor help messages, help can be a string, a function, a symbol, 
or a list (for the input editor options, the list is an &rest argument): 



string 



function or symbol 



list 



A format control string to be passed to format with one 
argument, the stream on which the help message is displayed. 

A function to display the help message. The function should 
take one argument, the stream on which the help message is 
displayed. 

If the first element is a string, it is a format control string to 
be passed to format with the remaining elements of the list 
as arguments. If the first element is a function or a symbol, 
it is a function to display the help message. The first 
argument to the function is the stream on which the help 
message is displayed, and the remaining arguments are the 
remaining elements of the list. 



7.6 Examples of Use of the Input Editor 



This series of examples shows several different ways of using the input editor, 
gradually increasing in complexity. The examples are also available in the file 
sys: examples; interaction.lisp. 

We refer to functions whose names begin with "read-" as "reading functions" or 
"readers", since they read individual characters and construct a Lisp object as a 
returned value. Examples of readers the Lisp system provides are read, readline, 
and read-delimiied-siring. read returns Lisp objecis of many types, readline 
and read-delimited-string return strings. 

read-two-lines-1 reads two lines of input from the console. You type each line in 
its own editing context. After you enter the first line by pressing RETURN, LINE, or 
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END, you can no longer rub out or otherwise edit any of the characters in the first 
line. You can type and edit only the second line at that point. 

(defun read-two-lines-1 () (list (readline) (readline))) 

read-two-lines-2 lets you edit both lines in a single context by using the 
with-input-editing special form. Even after entering the first line you can edit it. 
For example, the n-< input editor command moves the cursor to the first character 
of the first line, read-two-lines-2 also adds a stream parameter so that you can 
read from different streams without having to bind standard-input. You can also 
use this function for reading from noninteractive streams, such as file streams. 

(defun read-two-lines-2 (&optional (stream standard-input)) 

(with-input-editing (stream) (list (readline stream) (readline stream)))) 

read-two-lines-3 demonstrates the use of the rprompt input editor option and the 
:end-activation option for with-input-editing. When you invoke this function on 
an interactive stream you receive a prompt. This prompt is redisplayed if typeout to 
the stream occurs. This might happen if you press HELP or the window receives a 
notification. 

The :end-activation option defines #\end as an activation character. This lets 
you activate previous input to read-two-lines-3, after yanking and editing it, by 
pressing END. The rprompt and :end-activation options have no effect on the 
behavior of the function for noninteractive streams. 

(defun read-two-lines-3 (&optional (stream standard-input)) 
(with-input-editing-options ((rprompt "Type two lines: ")) 
(with-input-editing (stream :end-activation) 
(list (readline stream) (readline stream))))) 

read-n-lines is like read-two-lines except that you specify the number of lines to 
be read using the n-lines argument. It also uses a prompt function instead of a 
string to generate the prompt. 

(defun read-n-lines-prompt (stream ignore n-lines) 
(format stream "Type ~R line~:P:~%" n-lines)) 

(defun read-n-lines (n-lines &optional (stream standard-input)) 
(with-input-editing-options ((:prompt 'read-n-lines-prompt n-lines)) 
(with-input-editing (stream :end-activation) 
(loop repeat n-lines collect (readline stream))))) 

Next is an example of a simple sentence parser. It builds a list of strings and 
symbols that represent the words and punctuation marks of the sentence. A 
sentence may be any number of lines long. It is delimited by a period or a question 
mark. Words are delimited by a space, newline, or punctuation mark. This is also 
an example of a reading function written entirely in terms of :tyi as the primitive 
input operation. 
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(defun read-sentence-1 (ftoptional (stream standard-input)) 
(with- input-editing-options ((:prompt "Type a sentence: ")) 
(with-input-editing (stream) 
(loop named sentence 

with sentence = nil 

for word = (make-array 20. :type art-string : fill -pointer 0) 
do (loop for char = (send stream :tyi) 
do 
(cond ((memq char *(#\space #\return #/. #/? #/,)) 
(if (not (equal word "")) 
(push word sentence)) 
(selectq char 
((#\space #\return #/,) 
(return)) 
(#\. 
(push rperiod sentence) 
(return-from sentence (nreverse sentence))) 
(#\? 

(push :question-mark sentence) 
(return-from sentence (nreverse sentence))))) 
(t (array-push-extend word char)))))))) 

Following is a different sentence parser that calls read-delimited-string to 
accumulate characters into a string. It uses the :end-activation option for 
with-input-editing so that previous input to read-sentence-2 can be yanked, 
edited, and activated using the END key. When it detects incorrect uses of 
punctuation, it calls sysrparse-ferror to signal an error caught by the input editor. 
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(defun read-sentence-2 (&optional (stream standard-input)) 
(with-input-editing-options ((:prompt "Type a sentence: ")) 
(with-input-editing (stream :end-activation) 
(loop with sentence = nil 

do (multiple-value-bind (word nil delimiter) 
( read-del imi ted-str ing 
*(Aspace #\return #/. #/? #/, #/: #/;) stream) 
(if (not (equal word "")) 
(push word sentence)) 
(cond ((memq delimiter *(#\space #\return))) 
((null sentence) 
(if (eq delimiter #\end) 
(return nil) 
( sys : parse-f error 

"The punctuation mark /"~C/" occurred at the ~ 
beginning of the sentence." 
delimiter))) 
(( symbol p (car sentence)) 
( sys : parse- f error 
"The punctuation mark / H ~C/ H was typed after a ~@ A ." 
delimiter (car sentence))) 
(t (selectq delimiter 
(#/, 

(push • :comma sentence)) 
(#/: 

(push ' :colon sentence)) 
(#/; 

(push * :semicolon sentence)) 
(#/. 

(push *:period sentence) 
(return (nreverse sentence))) 
(#/? 

(push *:question-mark sentence) 
(return (nreverse sentence))))))))))) 

Sometimes an error in parsing is detected not by the function that invokes the input 
editor, but by some function that it calls. In the next example, read-time invokes 
time:parse-universal-time to do its parsing. If we did not use the 
condition-case form in read-time, we would enter the Debugger when 
time:parse-universal-time encountered incorrect input. The condition-case form 
encapsulates the original error in one of flavor sys:parse-ferror so that the input 
editor catches it. Alternately, we could define time:parse-error to be a subflavor of 
sys:parse-error. 
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(defun read-time (&optional (stream standard-input)) 
(with-input-editing (stream :line) 
(let ((string (readline-or-nil stream))) 
(when string 
(condition-case (error) 

(time: parse-universal -time string) 
(time: parse-error 
(sys: parse- f error M ~A M error))))))) 



7.7 Input Editor Messages to Interactive Streams 

rinput-editor read-function &rest read-args of Method 

si:interactive-stream 

Apply read-function to read-args after invoking the input editor. For more 
information: See the section "The Input Editor Program Interface", page 21. 

Normally a program does not send this message itself; it uses the special form 
with-input-editing. See the special form with-input-editing, page 25. 

:start-typeout type &optional spacing of sirinteractive-stream Method 

Informs the input editor that typeout to the window will follow. The word 
"typeout" is used in the name of this message because this is very similar to 
typeout in the editor, even though typeout windows are not actually used. 
type can be one of the following keywords: 

Keyword Action 

:insert Typeout is inserted before the current input, as is done 

with notifications or input editor documentation. 

:overwrite Like rinsert, but the next time :insert or :overwrite 

typeout is performed, this typeout is overwritten. 

rappend Typeout appears after the current input, which remains 

visible before the typeout. This is the style used by 
break. 

ttemporary Typeout appears after the current input and is erased 

after the user types a character. 

rclear-window The window is cleared, and typeout appears at the top. 
spacing can be one of the following keywords: 

Kp.vwnrd Artinn 

:none No spacing before typeout. 

:fresh-line Typeout begins at the beginning of a line. 
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rblank-line A blank line precedes typeout. 

If spacing is not specified, a default that depends on type is computed. 

si:*typeout-default* Variable 

Controls the style of typeout performed by the input editor. Permissible 
values are the keywords acceptable as the type argument to the 
:start-typeout method of sirinteractive-stream. These are rinsert, 
:overwrite, :append, rtemporary, and rclear-window. The default value 
is :overwrite. 

:finish-typeout &optional spacing erase? of Method 

si:interactive-stream 

Completes typeout to the window and causes the input buffer to be 
refreshed. In the case of rtemporary typeout, the erase? parameter is used 
to indicate whether or not the typeout overwrote part of the current input 
by wrapping around the screen. It is the responsibility of the program doing 
the typeout to keep track of how much is output. 

spacing can be one of the following keywords: 

Keyword Action 

:none No spacing before typeout. 

:fresh-line Typeout begins at the beginning of a line. 

:blank-line A blank line precedes typeout. 

If spacing is not specified, a default that depends on the type argument to 
the :start-typeout method is computed. 

:rescanning-p of sirinteractive-stream Method 

This message can be sent by a read function that uses the input editor to 
determine whether the next character returned by rtyi will come from the 
input buffer or from the keyboard. If t is returned, the input is being 
rescanned and the next character will come from the input buffer. If nil is 
returned, the next character will come from the keyboard. 

rforce-rescan of sirinteractive-stream Method 

This message can be sent by a read function that uses the input editor to 
force a rescan of the current input. Before this message is sent, usually 
some global state has changed and the contents of the input buffer are 
interpreted differently. 

rreplace-input n-chars string &optional (begin 0) end (rescan-mode Method 

rignore) of sirinteractive-stream 

This message can be sent by a read function that uses the input editor to 
provide completion of the current input. 
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n-chars specifies the number of characters to be removed from the end of the 
input buffer and erased from the screen. It can be an integer, a string, or 
nil: 

integer Remove n-chars characters from immediately before the 

scan pointer 

string Remove as many characters as the string contains 

nil Remove characters from the beginning of the input buffer 

to the scan pointer 

The substring of string determined by begin and end is then displayed on the 
screen, end defaults to (string-length string). The scan pointer is left after 
the string, and a rescan does not take place. If a rescan takes place at some 
later time, the characters in string are seen as input. 

rescan-mode specifies what action to take if the :replace-input message is 
sent when the scan pointer is not at the end of the input buffer: 

:ignore Don't perform the :replace-input operation. This is the 

default. 

:enable Perform the operation. 

terror Signal an error. 

:read-bp of sirinteractive-stream Method 

Returns the value of the scan pointer. This is for the benefit of read 
functions that might want to return a pointer into the input buffer when 
signalling an error of type sys:parse-error. 

:noise-string-out string &optional (rescan-mode :ignore) of Method 

sirinteractive-stream 

This message can be sent by a read function to display a string that is not to 
be treated as input. For example, the string might prompt the user for a 
particular kind of input, string is displayed on the screen without changing 
the scan pointer, and a rescan does not take place. If a rescan takes place at 
some later time, the characters in string are ignored. 

rescan-mode specifies what action to take if the :noise-string-out message is 
sent when the scan pointer is not at the end of the input buffer: 

rignore Don't perform the :noise-string-out operation. This is 

the default. 

:enabie Perform the operation. 

terror Signal an error. 
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8. The Command Processor Program Interface 



8.1 The Command Processor Reader 

read-command-or-form &optional (stream standard-input) &key Function 

(command-table si:*cp-comtab*) 
(dispatch-mode si:*cp-default-dispatch-mode*) 

(blank-line-mode 

si:*cp-default-blank-line-mode*) (prompt 
si:*cp-default-prompt*) 

Reads a form or a command processor command from stream. This is an 
appropriate function to use at top level in a command loop that uses the 
command processor. 

If stream is not supplied or is nil, it defaults to standard-input. 

If :dispatch-mode is specified, it is a keyword that indicates the command 
processor dispatch mode. The default is the value of 
si:*cp-default-dispatch-mode*. The initial default is 
:command-preferred. 

The actions that read-command-or-form takes depend on dispatch-mode: 

:form-only Calls read-form to read a form from stream. 

:command-only Calls read-command to read a command from stream. 

:form-preferred Calls read-form unless the first character typed is a 

command dispatch character (by default, a colon). In that 
case calls read-command. 

rcommand-preferred 

If the first character typed is a command dispatch 
character or an alphabetic character, calls read-command; 
otherwise, calls read-form. The user can evaluate a form 
that begins with an alphabetic character by first typing a 
form dispatch character (by default, a comma). 

For a general description of how the user enters a command: See the section 
"Entering a Command" in User's Guide to Symbolics Computers. 

If :command-table is supplied, it is a command table of the acceptable 
commands. The default command table is the value of si:*cp-comtab*. 
The initial default is the "User" command table. See the section "Command 
Processor Command Tables", page 52. 

If :blank-line-mode is supplied, it is a keyword that determines what action 
the command processor takes when the user types a blank line: 
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rreprompt Redisplay the prompt, if any. 

:beep Beep. 

rignore Do nothing. 

The default blank-line-mode is the value of 
sir*cp-default-blank-line-mode*. The initial default is rreprompt. 

If rprompt is supplied, it is a prompt option for the input editor to display at 
appropriate times, prompt can be nil, a string, a function, or a symbol other 
than nil (but not a list): See the section "Displaying Prompts in the Input 
Editor", page 33. The default prompt is the value of 
si:*cp-default-prompt*. The initial default is "Command: ". 

read-command-or-form returns a form. If read-command-or-form calls 
read-form to read from stream, it returns the form that read-form returns. 
If it calls read-command, it returns a list whose first element is a symbol, 
the name of the command, which is defined as a function. The remaining 
elements of the list are the arguments to the command, coerced to the 
appropriate types. Usually you execute the command by evaluating the 
returned list. 

read-command &optional (stream standard-input) &key Function 

(command-table si:*cp-comtab*) 
(blank- line-mode 

sir*cp-default-blank-line-mode*) (prompt 
sir*cp-default-prompt*) 
Reads a command processor command from stream, terminated by RETURN or 

END. 

If stream is not supplied or is nil, it defaults to standard-input. 

From the user's point of view, a command consists of a command name, 
positional arguments, and keyword arguments: See the section "Parts of a 
Command" in User's Guide to Symbolics Computers, read-command offers 
completion over command names, keyword argument names, and some 
argument values, and it completes any unspecified command components 
when the command is terminated: See the section "Completion in the 
Command Processor" in User's Guide to Symbolics Computers. 
read-command prompts for arguments and gives information about what 
sort of values are expected. Some arguments have default values. The user 
can press HELP to see documentation appropriate to the current stage of 
entering the command: See the section "Help in the Command Processor" in 

user enters a command: See the section "Entering a Command" in User's 
Guide to Symbolics Computers. 

If :command-table is supplied, it is a command table of the acceptable 
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commands. The default command table is the value of si:*cp-comtab*. 
The initial default is the "User" command table. See the section "Command 
Processor Command Tables", page 52. 

If :blank-line-mode is supplied, it is a keyword that determines what action 
the command processor takes when the user types a blank line: 

rreprompt Redisplay the prompt, if any. 

:beep Beep. 

rignore Do nothing. 

The default blank-line-mode is the value of 
si:*cp-default-blank-line-mode*. The initial default is rreprompt. 

If tprompt is supplied, it is a prompt option for the input editor to display at 
appropriate times, prompt can be nil, a string, a function, or a symbol other 
than nil (but not a list): See the section "Displaying Prompts in the Input 
Editor", page 33. The default prompt is the value of 
si:*cp-default-prompt*. The initial default is "Command: ". 

read-command returns two values. The first is a symbol, the name of the 
command, which is defined as a function. The second is a list of the 
arguments, converted to the appropriate types. Usually you execute the 
command by applying the first value (the function) to the second (the 
arguments). 

si:*cp-default-dispatch-mode* Variable 

The default command processor dispatch mode for read-command-or-form; 
a keyword. Possible values are :form-only, rform-preferred, 
:command-only, and :command-preferred. For the meanings of these 
values: See the section "Setting the Command Processor Mode" in User's 
Guide to Symbolics Computers. The default is rcommand-preferred. 

The dispatch mode used in Lisp Listeners and break loops is the value of 
si:*cp-dispatch-mode*. 

si:*cp-default-blank-line-mode* Variable 

The default command processor blank line mode for read-command and 
read-command-or-form. This is a keyword that determines what action 
the command processor takes when you type a blank line: 

rreprompt Redisplay the prompt, if any. This is the default. 

:beep Beep. 

rignore Do nothing. 

The blank line mode used in Lisp Listeners and break loops is the value of 
si:*cp-blank-line-mode*. 
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si:*cp-default-prompt* Variable 

The default command processor prompt option for read-command and 
read-command-or-form. The value of this variable is passed to the input 
editor as the value of the :prompt option. The value can be nil, a string, a 
function, or a symbol other than nil (but not a list): See the section 
"Displaying Prompts in the Input Editor", page 33. The default is 
"Command: ". 

The prompt used in Lisp Listeners and break loops is the value of 
si:*cp-prompt*. 



8.2 Defining a Command Processor Command 

define-cp-command name orgs &body body Special Form 

Defines a command processor command, name is a specification for the 
command name, args is a specification for the command arguments. 
define-cp-command defines a function that executes the command, with 
body as the body of the function. The name of the function is derived from 
name and the arguments from args. 

name is a symbol or a list. If name is a symbol, it is the name of the 
function that executes the command. By convention, the first four 
characters of the symbol's print name are usually "COM-". 

If name is a list, the first element is a symbol, the name of the function that 
executes the command. The remaining elements are alternating keywords 
and values. Each keyword-value pair is optional. Following are the 
permissible keywords and values: 

:name A string that represents the command name that the user 

types. If this option is not specified, the name is the 
result of calling string-capitalize-words on the symbol's 
print name, except that if the symbol's print name begins 
with "COM-", those characters are omitted from the 
command name. This option is useful for special 
capitalization of words, as in "Start GC". 

:comtab A command table or a string naming a command table in 

which to install the command. For example, to install a 
command in the "User" command table, you might specify 
"User" or the result of (si:find-comtab "User"). This 
option is evaluated. If it is not specified, the command is 
not installed in any command table and cannot be read. 
See the section "Command Processor Command Tables", 
page 52. 
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args is nil or a list of argument specifications for the arguments to the 
command and the function that executes the command. One element of 
args can be the symbol &key instead of an argument specification. All 
argument specifications preceding &key denote positional arguments to the 
command. All argument specifications following &key denote keyword 
arguments to both the command and the function that executes the 
command. 

An argument specification is a list that describes one argument to the 
command. 

The first element of an argument specification is a symbol. This symbol 
names a parameter in the arglist of the function that executes the command. 
This parameter is bound to the value of the argument when the function is 
called to execute the command, body can refer to the parameter. Unless a 
:name option is supplied later in the argument specification, the user-visible 
name of the argument is the result of calling string-capitalize-words on 
the symbol's print name. 

The second element of an argument specification is an argument type 
specification. This is a keyword or a list. If it is a keyword, it is the name 
of this argument's type. If it is a list, the first element is a keyword that is 
the name of this argument's type. The remaining elements supply 
information specific to the argument type. See the section "Command 
Processor Argument Types", page 48. 

The remaining elements of an argument specification are alternating 
keywords and values. Each keyword-value pair is optional. None of the 
values is evaluated. Following are the permissible keywords and values: 

rallow-multiple t if the argument can have multiple values; nil if the 
argument can have only one value. The user enters 
multiple values as a series separated by commas. These 
are passed to the command ftinction as a list of values. 
The default is nil. 

rconfirm t if the argument requires confirmation by the user; nil if 

it does not. The default is nil. 

:default A form to be evaluated when the argument is read to 

return the default value for the argument. If 
rallow-multiple is specified with a value of t, the form 
must return a list of values. The form can refer to 
parameters defmed for any positional arguments (but not 
keyword arguments) specified in args before this argument 
specification. At the time the form is evaluated, these 
parameters are bound to the values of arguments already 
read. 
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For a positional argument, if rdefault is not supplied the 
argument has no default value. When the command is 
read, the user is forced to supply a value. 

For a keyword argument, the default used depends on 
what combination of rdefault and rmentioned-default 

options is supplied: 

Both Use the :mentioned-default default if 

the user types the name of the 
argument; otherwise use the rdefault 
default. 

rmentioned-default only 

Use the rmentioned-default default. 

rdefault only Use the rdefault default. 

Neither If the user does not type the name of 

the argument, the default is nil. If the 
user types the name of the argument, 
the argument has no default value, and 
the user is forced to supply a value. 

rmentioned-default 

For a keyword argument, a form to be evaluated when the 
argument is read to return the default value if the user 
types the name of the argument. If rallow-multiple is 
specified with a value of t, the form must return a list of 
values. The form can refer to parameters defined for any 
positional arguments (but not keyword arguments) specified 
in args before this argument specification. At the time the 
form is evaluated, these parameters are bound to the 
values of arguments already read. 

The default used depends on what combination of rdefault 
and rmentioned-default options is supplied: 

Both Use the rmentioned-default default if 

the user types the name of the 
argument; otherwise use the rdefault 
default. 

rmentioned-default only 

Use the rmentioned-default default. 

rdefault only Use the rdefault default. 

Neither If the user does not type the name of 

the argument, the default is nil. If the 
user types the name of the argument, 
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the argument has no default value, and 
the user is forced to supply a value. 

Use this option when you want the default to depend on 
whether or not the user types the argument name. For 
example, the Delete File command has an Expunge 
keyword argument whose :default default is No and 
whose :mentioned-default default is Yes. 

documentation A string, usually short, that documents the meaning of the 
argument. The string is displayed after the argument 
name if the user presses HELP while entering the 
argument. For example, the string for the argument to 
the Show Hosts command is "Hosts about which to display 
status information". The default HELP display depends on 
the argument type. 



:name 



rprompt 



A string that represents the user-visible name of the 
argument. The default name is the result of calling 
string-capitalize-words on the print name of the symbol 
that is the first element of the argument specification. 
This option is useful when you want the user-visible name 
of the argument to differ from the parameter bound to the 
argument value. For example, you might want the user- 
visible name to be Base without binding the special variable 
base. 

A string that represents a prompt for the argument, or a 
form to be evaluated when the command is read to return 
a prompt string. The form is evaluated with the symbol 
=default= bound to the argument default. =default= is 
interned in the package that is the value of package 
when the define-cp-command form is evaluated. The 
default prompt depends on the argument type. See the 
section "Command Processor Argument Types", page 48. 



Example: 



(define-cp-command (com-edit-file :comtab "Global") 
((file : pathname 

:allow-multiple t 

:default *(,(fs: default-pathname)) 

: prompt 

(format nil "file to edit [default ~A]" (first =default=)) 

: documentation "Files to edit")) 
(ed file) 

(send standard-output : fresh-line) 
(send standard-output :tyo #\newline) 
(values)) 



48 

Programming the User Interface 



March 1985 



8.3 Command Processor Argument Types 



Following is a description of each command processor argument type. When you use 
define-cp-command to define a command, the argument type keyword is the 
second element of an argument specification, or the car of the second element. If 
the second element is a list, the elements of its cdr are the type-specific information 
described for each argument type. See the special form define-cp-command, page 
44. 

The default prompt and help message for each type provide information about the 
kind of values expected. In general, when the possible values are members of a 
restricted set, the default help message lists the possible values. The default prompt 
sometimes lists the possible values. For some types completion is provided over the 
set of possible values. 



rboolean 



remuneration 



mumber 



rinteger 



The value is t if the user types 'Yes" and nil if the user types 
"No". Completion is provided over these choices. 

Type-specific information: None. 

The value is one of a restricted set of strings or objects that can 
be coerced to strings, specified by the type-specific information. 
The user must type a string associated with one of the elements 
of the set. Completion is provided over this set. 

Type-specific information: The strings or objects that can be 
coerced to strings that make up the set of permissible values for 
the argument. Often these are keyword symbols. For example: 

( remuneration :yes :no :ask) 

The default prompt lists strings formed by calling 
string-capitalize-words (but keeping hyphens) on each element 
of the set of permissible values. 

The value is a number. 

Type-specific information: The symbol :base followed by an 
integer, the base in which the number is read. If :base is not 
supplied the number is read in decimal. 

The default prompt displays the input base (if other than decimal) 
and the default. 

The value is an integer. 

Type-specific information: Alternating keywords and values: 



:base 



An integer, the base in which the integer is 
read. If :base is not supplied the integer is 
read in decimal. 
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:from 



:to 



A number. The integer must be greater than 
or equal to this. If :from is not supplied the 
integer has no lower limit. 

A number. The integer must be less than or 
equal to this. If :to is not supplied the integer 
has no upper limit. 



The default prompt displays the input base (if other than decimal) 
and the default. 

rstring The value is a string. 

Type-specific-information: None. 

:pathname If no type-specific information is supplied, the value is a pathname 

derived from merging the string the user types with the default 
and a default version of mewest. Completion is provided using 
the system pathname-completion facility. 

Type-specific information: Alternating keywords and values: 

rpathname-default 

A form to be evaluated when the command is 
read to return a default for pathname merging. 
The form can return anything suitable as the 
second argument to fsrmerge-pathnames. 
This is used as the default only if the 
argument default is not a pathname; if the 
argument default is a pathname, that 
pathname is used as the default for merging. 
If the argument default is not a pathname and 
if rpathname-default is not supplied, the 
default is the result of (fsrdefault-pathname). 

rdefault-version A number or symbol suitable as the third 

argument to fs:merge-pathnames, to be used 
as the default version for the merged 
pathname. 

:or-none If t and the user types "none", the value of the 

argument is :none. 



:or-no 



:or-query 



:raw 



If t and the user types "no", the value of the 
argument is :no. 

If t and the user types "query", the value of 
the argument is :query. 

The value of the argument is the result of 
calling fstparse-pathname with arguments of 
the string the user types, nil, and the default. 
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The default prompt displays the default pathname. 

:host The value is the network host whose name the user types, unless 

the user types "Local", "All", or "None": 



"Local" 


The local host 


"All" 


rail 


"None" 


nil 



Type-specific-information: None. 

rprinter The value is the printer object whose name the user types, unless 

the user types "None". In that case the value is nil. The value 
can be any printer accessible from the user's site. Completion is 
provided over the set of printers at the user's site. 

Type-specific-information: None. 

:date The value is a universal time integer. When the user's input is 

parsed, missing components are defaulted to the beginning of the 
smallest unsupplied unit of time. Thus, "5 pm" is the same as "5 
pm today", whether typed before or after 5 pm. 

Type-specific-information: None. 

rpackage If no type-specific information is supplied, the value is the package 

whose name the user types. Completion is provided over the set 
of existing packages. 

Type-specific information: The keyword tall-allowed. If this is 
supplied and the user types "All", the value of the argument is 
rail. 

:font If no type-specific information is supplied, the value depends on 

what the user types: 

Nothing If no default exists, the value is nil. 

Name of a loaded font 

The value is the font. 

Name of a known but not loaded font 

The value is the print name of the symbol in 
the fonts package. 

Name of an unknown font 

The value is the string the user types. 

ComnlRt.ion is nrnvirlpri nver the sfit. nf known fonts 
Type-specific information: Alternating keywords and values: 



March 1985 



51 
Interactive Streams 



:or-default If t and the user types "Default-Font", the 

value of the argument is :default-font. 

:known-only If t and the user types the name of an 

unknown font, an error is signalled and caught 
by the input editor. 

:loaded-only If t and the user types the name of a font that 
is unknown or is not loaded, an error is 
signalled and caught by the input editor. 

rsystem If no type-specific information is supplied, the value is the system 

whose name the user types if the system is loaded, or the string 
the user types if it is not the name of a loaded system. 
Completion is provided over the set of loaded systems. 

Type-specific information: Keywords: 

:loaded-only If the user types "All", the value of the 

argument is tall. Otherwise, unless the user 
types the name of a loaded system, an error is 
signalled and caught by the input editor. 

:patchable-only If the user types the name of a system that is 
loaded but not patchable, the value of the 
argument is the string the user types, unless 
:loaded-only is also specified. In that case an 
error is signalled and caught by the input 
editor. 

:activity The value is an element of the list that is the value of 

tv:*select-keys*. This is a list of four elements, the third of 
which is the string that the user types naming the activity. For 
some activities, the user can also type a nickname for the name of 
the activity. In that case the string the user types is not the 
same as the third element of the returned list. 

The elements of the returned list correspond to the first four 
arguments to tv:add-select-key. For information: See the 
function tv:add-select-key, page 137. 

Completion is provided over the set of existing activities. 

Type-specific information: None. 

:documentation-topic 

The value is an element of the completion aarray used by the 
Document Examiner. This is a list determined by the string the 
user types. The first element of the list is the string, and the 
remaining elements are associated function specs that have 
documentation available to the Document Examiner. Completion 
is provided over the set of defined documentation topics. 
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Type-specific information: None. 

rmake-system-version 

The value is an integer, symbol, or string suitable as an argument 
to the rversion make-system option. If the user types a 
nonnegative integer, the value is that integer, unless :no-number 
is specified in the type-specific information. If the user types a 
string associated with one of the elements specified by the type- 
specific information, the value is that element. Otherwise, the 
value is the string the user types. Completion is provided over 
the set of values specified by the type-specific information. 

Type-specific information: Strings or objects that can be coerced 
to strings that make up the set of permissible values for the 
argument. Usually this includes symbols like mewest or 
rreleased. If :no-number is one of these, integers (and 
:no-number) are not permissible values. 

The default prompt lists strings formed by calling 
string-capitalize-words (but keeping hyphens) on each element 
of the set of permissible values. 



8.4 Command Processor Command Tables 

A command table is an object that identifies a set of commands that are permissible 
in some context. Command tables can be arranged in a hierarchy, so that 
subordinate command tables inherit commands from their superiors. The set of 
permissible commands for a command table includes the commands in that command 
table and the commands in all superior command tables. 

When a command is read, using read-command or read-command-or-form, the 
set of permissible commands is determined by the command table that is the value 
of the :command-table argument to the reading function. Only commands in that 
command table or a superior can be read. You install a command in a command 
table at the time you define the command, using the tcomtab option in the 
command-name specification for define-cp-commancL See the special form 
define-cp-command, page 44. 

The command processor maintains a global registry of all command tables. You find 
a command table by using the function si:find-comtab. This function is especially 
useful in supplying the :command-table argument to read-command or 
read-command-or-form. Use sircreate-comtab to create a command table, and 
shdelete-comtab to delete one. Two useful existing command tables are the 
"Cloboi" «Iiu the "Udci" cviiimemu lauxtrs. The variable siz^cp-comiab" is Dound 10 
the current command table in Lisp Listeners and break loops, and it is also the 
default command table for read-command and read-command-or-form. 
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si:find-comtab name Function 

Returns a command processor command table if it exists in the command 
table registry, or nil if the command table cannot be found. 

name can be a command table, a string, or an object that can be coerced to a 
string. If name is a command table, sirfind-command returns name. If 
name is a string or an object that can be coerced to a string, si:find-comtab 
returns the command table whose name is that string. 

si:create-comtab name &optional (superior Function 

(si:find-comtab "Global")) &rest init-options 
Creates and returns a command processor command table, and installs the 
command table in the command table registry. 

name is a string or an object that can be coerced to a string. The string is 
the name of the command table, to be used as the argument to 
si:find-comtab. 

superior is a command table, or a string or an object that can be coerced to a 
string that names a command table, superior is the superior of the 
command table to be created. The set of permissible commands includes the 
commands in the command table and the commands in all superior command 
tables. The default superior is the "Global" command table. 

init-options are optional alternating keywords and values: 

:command-table-size 

The expected number of commands in the command table. 
The default is 25 (decimal). If the number of commands 
exceeds this figure, the command table is expanded 
automatically. 

:command-table-delims 

A list of characters used to delimit words for completion of 
the names of commands. The default is (#\space). 

si:delete-comtab name Function 

Removes a command processor command table from the command table 
registry. The returned value is not defined. 

name is a command table, or a string or an object that can be coerced to a 
string that names a command table. 

si:*cp-comtab* Variable 

The command processor command table that specifies the acceptable 
commands in Lisp Listeners and break loops. The value of this variable is 
also the default command table for read-command and 
read-command-or-form. The default is the result of 
(shfind-comtab "User"), the "User" command table. 
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9. Querying the User 



The following functions provide a convenient and consistent interface for asking 
questions of the user. Questions are printed and the answers are read on the 
stream query-io, which normally is synonymous with terminal-io but can be 
rebound to another stream for special applications. 

y-or-n-p &optional message (query-io query-io) Function 

This is used for asking the user a question whose answer is either "yes" or 
"no". It types out message (if any), reads a one-character answer, echoes it 
as "Yes" or "No", and returns t if the answer is "yes" or nil if the answer is 
"no". The characters that mean "yes" are #/Y, #/T, and #\space. The 
characters that mean "no" are #/N and #\rubout. If any other character 
is typed, the function beeps and demand a "Y or N" answer. 

If the message argument is supplied, it is printed on a fresh line (using the 
:fresh-line stream operation). Otherwise the caller is assumed to have 
printed the message already. If you want a question mark and/or a space at 
the end of the message, you must put it there yourself; y-or-n-p does not 
add it. query-io defaults to the value of query-io. 

y-or-n-p should only be used for questions that the user knows are coming. 
If the user is not going to be anticipating the question (for example, if the 
question is "Do you really want to delete all of your files?" out of the blue) 
then y-or-n-p should not be used, because the user might type ahead a T, Y, 
N, space, or rubout, and therefore accidentally answer the question. In such 
cases, use yes-or-no-p. 

y-or-n-p supplies a prompt that indicates which form of answer (single letter 
or full word plus RETURN) is required. This prompt is appended to any 
message that you supply with the function. 

(y-or-n-p "More? ") => 
More? (Y or N) Yes. 

yes-or-no-p &optional message (query-io query-io) Function 

This is used for asking the user a question whose answer is either "Yes" or 
"No". It types out message (if any), beeps, and reads in a line from the 
keyboard. If the line is the string "Yes", it returns t. If the line is "No", it 
returns nil. (Case is ignored, as are leading and trailing spaces and tabs.) If 
the input line is anything else, yes-or-no-p beeps and demands a "yes" or 
"no" answer. 

If the message argument is supplied, it is printed on a fresh line (using the 
:fresh-line stream operation). Otherwise the caller is assumed to have 
printed the message already. If you want a question mark and/or a space at 
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the end of the message, you must put it there yourself; yes-or-no-p does not 
add it. query-io defaults to the value of query-io. 

To allow the user to answer a yes-or-no question with a single character, use 
y-or-n-p. yes-or-no-p should be used for unanticipated or momentous 
questions; this is why it beeps and why it requires several keystrokes to 
answer it. 

yes-or-no-p supplies a prompt that indicates which form of answer (single 
letter or full word plus RETURN) is required. This prompt is appended to any 
message that you supply with the function. 

(yes-or-no-p "Detonate terminal? ") => 
Detonate terminal? (Yes or No) no 

fquery options &optional fquery-formot-string &rest Function 

fquery-format-args 
Asks a question, printed by (format query-io format-string format-args...), 
and returns the answer, fquery takes care of checking for valid answers, 
reprinting the question when the user clears the screen, giving help, and so 
forth. 

options is a list of alternating keywords and values, used to select among a 
variety of features. Most callers have a constant list that they pass as 
options (rather than consing up a list whose contents varies). The keywords 
allowed are: 

:type What type of answer is expected. The currently defined types are 
:tyi (a single character), :readline (a line terminated by a carriage 
return), and :mini-buffer-or-readline. :tyi is the default. 

:mini-buffer-or-readline is like the rreadline value. The 
exception is that if fquery is called from inside Zwei or Zmail, the 
line of text is read from the minibuffer instead of from the 
query-io stream. The idea of this feature is to let you write 
things that work equally well inside Zwei or on their own; if you 
use this value, you make it easier for your code to be integrated 
into a Zwei extension. 

rchoices Defines the allowed answers. The allowed forms of choices are 
complicated and explained below. The default is the same set of 
choices as the y-or-n-p function. Note that the :type and 
rchoices options should be consistent with each other. 

:list-choices 

If t, the allowed choices are listed (in parentheses) after the 

qucotiuii. xiie ueiauil is l; supplying 1111 causes Lie cnuices iiul LU 

be listed unless the user tries to give an answer that is not one of 
the allowed choices. 
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:help-function 

Specifies a function to be called if the user presses the help key. 
The default help function simply lists the available choices. 
Specifying nil disables special treatment of HELP. If you specify a 
help function, it should take one argument, the stream on which 
to display the help message. The function can get the list of 
available choices from the value of the special variable 
format:fquery-choices. 

rsignal-condition 

Basically a way to intervene and provide an answer to a query 
without asking the user. 

The default for rsignal-condition is nil. When its value is t, the 
fquery function signals an fquery condition with proceed type of 
:choice before prompting the user. Any handler can invoke the 
rchoice proceed type in order to return a value from fquery. 
When no handler handles the condition, fquery proceeds normally 
and queries the user. 

fquery Flavor 

fquery is a simple condition built on condition. It is 
signalled by the fquery function when its 
:signal-condition option is t. The messages examine the 
arguments given to the fquery function. 

Message Value returned 

:options Returns the first argument to the 

fquery function. 
:format-string Returns the second argument to the 

fquery function (its format control string 

or prompt). 
:format-args Returns the rest of the arguments to the 

fquery function (the arguments to its 

format control string). 

The :choice proceed type is provided. It has one 
argument, which is a value to be returned from the call to 
the fquery function. 

The following example answers "yes" to every "Delete this entry?" 
query occurring inside do-it that has rsignal-condition t: 
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(condition-bind 

((fquery #'( lambda (condition) 

(and (send condition ': proceed- type-p * rchoice) 
(equal (send condition ': format-string) 

"Delete this entry? ") 
(values 'rchoice t))))) 
(do-it)) 

:fresh-line 

If t, query-io is advanced to a fresh line before asking the 
question. If nil, the question is printed wherever the cursor was 
left by previous typeout. The default is t. 

:beep If t, fquery beeps to attract the user's attention to the question. 
The default is nil, which means not to beep unless the user tries 
to give an answer that is not one of the allowed choices. 

:clear-input 

If t, fquery throws away typeahead before reading the user's 
response to the question. Use this for unexpected questions. The 
default is nil, which means not to throw away typeahead unless 
the user tries to give an answer that is not one of the allowed 
choices. In that case, typeahead is discarded since the user 
probably wasn't expecting the question. 

rselect If t and query-io is a visible window, that window is temporarily 
selected while the question is being asked. The default is nil. 

:make-complete 

If t and query-io is a typeout-window, the window is "made 
complete" after the question has been answered. This tells the 
system that the contents of the window are no longer useful. The 
default is t. 

rstream Has as its value the stream to use for both input and output. The 
default value is the value of the global variable query-io. 

:no-input-save 

If t, tells the input editor not to put the response to the question 
into its history. The default is nil. 

rstatus This option takes effect only if query-io is a window and :type is 
:tyi. If the value is tselected and the window becomes deselected 
while fquery is waiting for input, fquery returns :status. If the 
value is :exposed and the window becomes deexposed or deselected 
while fquery is waiting for input, fquery returns rstatus. If the 
value is nil, fquery continues to wait for input when the window 

is uecA^useu ui ueotaec Uai. a lie utrmuil is uii. 

This option is intended for queries that appear in temporary 
windows that might become deexposed or deselected before the 
user responds. 
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The argument to the :choices option is a list each of whose elements is a 
choice (with one exception, described in the next paragraph). A choice is a 
list whose cdr is a list of the user inputs that correspond to that choice. 
These should be characters for :type :tyi or strings for :type :readline. 
The car of a choice is either a symbol that fquery should return if the user 
answers with that choice, or a list whose first element is such a symbol and 
whose second element is the string to be echoed when the user selects the 
choice. In the former case nothing is echoed. In most cases :type rreadline 
would use the first format, since the user's input has already been echoed, 
and :type :tyi would use the second format, since the input has not been 
echoed and furthermore is a single character, which would not be meaningful 
to see on the display. 

The last element in the list of choices can be the symbol :any (instead of 
being a list, like all other choices). Then if the user gives some response that 
is not one of the other choices, fquery does not complain and reprompt the 
user, but instead returns what the user typed (a single character or a string, 
depending on the :type option). 

For example, the yes-or-no-p function uses this list of choices: 

((t "Yes") (nil "No")) 

and the y-or-n-p function uses this list: 

(((t "Yes.") #/Y #/T #\space) 
((nil "No.") #/N #\rubout)) 

If you want to use the formatted output functions instead of format to 
produce the prompting message, write: 

(fquery options ( format: out fmt exp-or-string exp-or-string ...)) 

format.-outfmt puts the output into a list of a string, which makes format 
print it exactly as is. There is no need to supply additional arguments to the 
fquery unless it signals a condition. In that case the arguments might be 
passed so that the condition handler can see them. 

prompt-and-read type &optional format-string &rest format-args Function 

prompt-and-read prompts the user, with format-string and its arguments as 
the prompt. It uses format to query-io to produce the prompt; it reads 
from the query-io stream, calling the reading function associated with the 
type keyword. If format-string is not specified, it generates a prompt 
appropriate to type. The type argument can be a list in which the first 
element is the type keyword and the rest are keyword/value pairs to serve as 
arguments to the reading function. (For the robject and :object-list types, 
type must be a list with the :class keyword supplied.) prompt-and-read 
returns whatever the reading function returns. 

This is an appropriate function to call for collecting input from the user. Its 
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main advantages are that it does type checking on the input the user types 
and that it takes care of redisplaying the prompt at appropriate times (for 
example, after the screen has been refreshed or after a notification arrives). 

(prompt-and-read : number "Please enter a number: ") => 

Please enter a number: 4 

4 

(prompt-and-read :string "Please enter a string: ") => 

Please enter a string: 4 

It expects to collect input of type type, where type is a keyword. It handles 
the following types of input: 

Option Action 

:eval-form Reads a Lisp form. Evaluates it and returns the first 

value. Asks for confirmation of nonconstant values. The 
Debugger uses this to prompt for a form to evaluate. 

:eval-form-or-end 

Reads a Lisp form or just END. Evaluates it and returns 
the first value for a form. Returns two values, nil and 
rend, for END. Asks for confirmation of nonconstant 
values. The Debugger uses this to prompt for a form to 
evaluate. 

expression Reads a Lisp expression and returns the expression 

without evaluating it. 

:expression-or-end 

Reads a Lisp expression or just END. It returns the 
expression without evaluating it. If the user just presses 
END, it returns two values, nil and tend. 

:character Reads and returns a character. The returned value is a 

character code (an integer). 

rsymbol Reads and returns a symbol. 

(:function-spec :defined-p defined-p) 

Reads and returns a function spec. If :defined-p is 
specified with a value other than nil, the function spec 
must be defined as a function. The default for defined-p 
is nil. 

:string Reads a string terminated by return, line, or END. It 

l»Q+llt»Tia +Vl« owinfir e+wmr* tttVi#%»% 4-V»«-» h^w'iom lr* ^»-^w.«~4-«. 
r -j „~w~. ~--w ~~..~~ b .►/ -"•CV 

:string-trim Reads a string terminated by return, line, or END. It 

trims any leading or trailing white space. It returns the 
empty string when the string is empty. 
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rstring-or-nil Reads a string terminated by RETURN, LINE, or END. It 
trims any leading or trailing white space. It returns nil 
when the string is empty. 

(:string-list ror-nil or-nil) 

Reads a series of strings separated by commas and 
terminated by RETURN, LINE, or END. It returns a list of 
the strings, unless or-nil is not nil and the user just 
presses return, line, or end. In that case it returns nil. 
The default for or-nil is t. 

(rdelimited-string :delimiter delimiter :visible-delimiter visible-delimiter 
:buffer-size size :or-nil or-nil) 
Reads characters until the user types a delimiter, then 
returns the input as a string without the delimiter. 

rdelimiter and rvisible-delimiter are mutually exclusive. 
If one of them is specified, it must be nil or a list of 
characters that delimit the string. If neither is specified, 
or if one is specified with a value of nil, the only delimiter 
is #\end. 

The difference between rdelimiter and rvisible-delimiter 
is that if a prompt is supplied as the second argument to 
prompt-and-read, the rvisible-delimiter characters are 
displayed to the user after the prompt, but the :delimiter 
characters is not. If a prompt is supplied and neither 
rdelimiter nor :visible-delimiter is specified, the 
delimiting character is not displayed. If no prompt is 
supplied, the delimiting characters are always displayed, 
whether they come from rdelimiter, rvisible-delimiter, 
or the default delimiter. 

If :buffer-size is specified, an initial buffer of size size 
characters is allocated; otherwise, the initial size is 
100. characters. It returns the empty string when the 
string is empty, unless :or-nil is specified with a value 
other than nil. In that case it returns nil when the 
string is empty. The default for or-nil is nil. 

(:delimited-string-or-nil rdelimiter delimiter rvisible-delimiter 
visible-delimiter :buffer-size size) 
The same as (delimited-string rdelimiter delimiter 
rvisible-delimiter visible-delimiter rbuffer-size size 
ror-nil t). This option is obsolete. 

(♦.complete-string ralist alist rdelimiters delimiters rimpossible-is-ok 
impossible-is-ok ror-nil or-nil :complete-on-space 

complete-on-space) 

Reads and returns a (possibly completed) string, terminated 

by RETURN, LINE, or END. 
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If the user presses complete, the input so far is completed 
over the set of possibilities determined by alist. If 
complete-on-space is not nil, the input is also completed 
when the user presses SPACE at the end of the input 
buffer. The default for complete-on-space is t. 

If the user presses c-?, the possible completions of the 
input are displayed. If the user presses HELP, the possible 
completions are displayed unless many exist; in that case a 
general help message is displayed. 

The style of completion is the same as that offered by 
Zwei. alist can be nil, an alist, an art-q-list array, or a 
keyword: 

nil No completion is offered. This is the 

default. 

alist The car of each alist element is a string 

representing one possible completion. 

array Each element is a list whose car is a 

string representing one possible 
completion. The array must be sorted 
alphabetically on the cars of the 
elements. 

keyword If the symbol is :zmacs, completion is 

offered over the definitions in Zmacs 
buffers. If the symbol is :flavors, 
completion is offered over all flavor 
names. 

delimiters is nil or a list of characters that delimit 
"chunks" for completion. As in Zwei, completion works by 
matching initial substrings of "chunks" of text. If 
delimiters is nil, the entire text of the input is a single 
"chunk". The default is nil. 

If or-nil is nil and the user just presses RETURN, LINE, or 
END, :complete-string waits for more input. If or-nil is 
not nil and the user just presses RETURN, LINE, or END, it 
returns nil. The default for or-nil is t. 

If the user presses return, line, or end and the input 
buffer is not empty, the input is completed as far as 
possioie. it tne completed string is tne car or an alist 
element, the completed string is returned. Otherwise, if 
the user pressed END or if impossible-is-ok is nil, 
rcomplete-string waits for more input. If the user 
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pressed return or line or if impossible-is-ok is not nil, the 
completed string is returned. The default for 
impossible-is-ok is t. 

Unless :complete-string returns nil, it also returns a 
second value, a list of the alist elements that represent 
possible completions of the returned string. 

(:flavor-name :impossible-is-ok impossible-is-ok) 

Reads and returns the name of a flavor, terminated by 
RETURN, LINE, or END. The user can type the flavor name 
with or without a package prefix. 

If the user presses COMPLETE, the input so far is completed 
over the set of defined flavors. If the user presses c-?, the 
possible completions of the input are displayed. If the user 
presses HELP, the possible completions are displayed unless 
many exist; in that case a general help message is 
displayed. 

If the user presses return, line, or END and the input 
buffer is not empty, the input is completed as far as 
possible. If the completed input is the name of a flavor, 
the flavor name (a symbol in the appropriate package) is 
returned. Otherwise, if the user pressed END, 
:flavor-name waits for more input. If the user pressed 
return or LINE and if impossible-is-ok is not nil, the 
completed input is returned as a symbol. If the user 
pressed RETURN or LINE and if impossible-is-ok is nil, an 
error is signalled and caught by the input editor. The 
default for impossible-is-ok is t. 

(: number :base input-base :or-nil or-nil) 

Reads and returns a number, terminated by RETURN, LINE, 
or END. If :base is specified, the number is read in base 
input-base; otherwise, it is read as a decimal number. If 
:or-nil is specified with a value other than nil, it returns 
nil if the user just presses RETURN, LINE, or END. The 
default for or-nil is nil. 

(:number-or-nil :base input-base) 

The same as (rnumber :base input-base :or-nil t). This 
option is obsolete. 

(:decimal-number :or-nil or-nil) 

The same as (rnumber :base 10. :or-nil or-nil). This 
option is obsolete. 

:decimal-number-or-nil 

The same as Onumber :base 10. :or-nil t). This option 
is obsolete. 
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(:integer :base input-base :or-nil or-nil :from from :to to) 

Reads and returns an integer, terminated by RETURN, LINE, 
or end. If :base is specified, the integer is read in base 
input-base; otherwise, it is read as a decimal number. If 
:or-nil is specified with a value other than nil, it returns 
nil if the user just presses return, line, or end. The 
default for or-nil is nil. If :from is specified, the integer 
must be greater than or equal to from. If :to is specified, 
the integer must be less than or equal to to. The default 
for from and to is to place no limits on the integer. 

(:date :past-p past-p :never-p never-p :base-time base-time :or-nil or-nil) 
Reads and returns a date, terminated by RETURN, LINE, or 
END. The returned date is a universal-time integer of the 
form returned by time:parse-universal-time. If :past-p 
is specified with a value other than nil, an ambiguous date 
is interpreted as being in the past, relative to the base 
time; otherwise, it is interpreted as being in the future. 
The default for past-p is nil. If :never-p is specified with 
a value other than nil, it returns nil if the user types 
"never". The default for never-p is nil. If :base-time is 
specified, it must be a universal-time integer that is used 
to fill in components that the user omits. If :base-time is 
not specified, the time when the user's input is read is 
used as the base time. 

(:past-date :never-p never-p :base-time base-time :or-nil or-nil) 
The same as (:date :past-p t :never-p never-p 
:base-time base-time :or-nil or-nil). This option is 
obsolete. 

(:date-or-never :past-p past-p :base-time base-time :or-nil or-nil) 

The same as (:date :past-p past-p :never-p t :base-time 

base-time :or-nil or-nil). This option is obsolete. 

(:past-date-or-never :base-time base-time :or-nil or-nil) 

The same as (:date :past-p t :never-p t :base-time 
base-time :or-nil or-nil). This option is obsolete. 

:time-interval-or-never 

Reads a time interval, terminated by RETURN, LINE, or END. 
The interval must be either "never" or alternating 
numbers and units of time; the units can include seconds, 
minutes, hours, days, weeks, or years. It returns nil if 
the user types "never". Otherwise, it returns an integer 
representing the number of seconds in the time interval. 

Example: 
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(prompt-and-read :time-interval-or-never) 

Enter a time interval, or "never": 1 day 2 hrs 13 min => 

94380. 

^pathname tdefault default :visible-default visible-default 
:default-version version :or-nil or-nil) 
Reads a pathname, terminated by RETURN, LINE, or END, 
merging it with a default. 

tdefault and :visible-default are mutually exclusive. If 
either is specified, its value can be nil, a pathname, a 
pathname string, or an alist of hosts and pathnames of 
the sort that is the value of 

fs:*default-pathname-defaults*. If the value is nil or a 
defaults alist, the default used is the result of calling 
fsrdefault-pathname on the value. If the value is a 
pathname or a pathname string, the default used is the 
result of calling fs:parse-pathname on the value. If 
neither rdefault nor :visible-default is specified, the 
default used is the result of (fsrdefault-pathname). 

The difference between rdefault and :visible-default is 
that if a prompt is supplied as the second argument to 
prompt-and-read, the -.visible-default pathname is 
displayed to the user after the prompt, but the rdefault 
pathname is not. If a prompt is supplied and neither 
:default nor :visible-default is specified, the default 
pathname is not displayed. If no prompt is supplied, the 
default pathname is always displayed, whether it comes 
from :default, :visible-default, or the default default. 

If -.default-version is not specified, the default version is 
nil. If rdefault-version is specified, its value should be 
an integer or keyword suitable as the third argument to 
fs:merge-pathnames. 

If the user just presses RETURN or LINE this option returns 
the default pathname. If the user just presses END this 
option returns the default pathname, unless :or-nil is 
specified with a value other than nil. In that case it 
returns nil. Otherwise this option returns the pathname 
the user typed, merged against the default and the default 
version. The default for or-nil is nil. 

If the user presses COMPLETE an attempt is made to 
complete the pathname string typed so far. If the user 
presses END after typing some text, an attempt is made to 
complete the pathname string, and if completion is 
successful the merged pathname is returned. 
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Example: 

(prompt-and-read 
'(: pathname :visible-default ,my-defaults-alist) 
"Enter a name")) 

(:pathname-or-nil rdefault default rvisible-default visible-default 
rdefault-version version) 
The same as (rpathname rdefault default 
rvisible-default visible-default :default-version version 
:or-nil t). This option is obsolete. 

(:pathname-list rdefault default rvisible-default visible-default :or-nil 
or-nil) 

Reads a series of pathnames, separated by commas and 
terminated by return, line, or end. The meaning of 
rdefault and rvisible-default is the same as for the 
rpathname option. rpathname-list merges the 
pathnames with the default and with a default version of 
mewest. It returns a list of the merged pathnames, 
unless or-nil is not nil and the user just presses RETURN, 
LINE, or END. In that case it returns nil. The default for 
or-nil is t. 

(:host :host-type type rdefault default :or-nil or-nil) 

Reads the name of a host, terminated by RETURN, LINE, or 

END. 

:host-type is a keyword that determines what kind of 
input is acceptable: 

rphysical The name of a network host. This is 

the default. 

:chaos-only The name of a network host on the 

chaosnet. 

:or-local The name of a network host or "local", 

meaning the local host. 

rpathname The name of a pathname host or "local", 

meaning the local host. 

:or-pathname The name of a network host, a 

pathname host, or "local", meaning the 
local host. 

If rdefault is specified, it should be a network host or the 
name of a host as a symbol or string. If rdefault is 
specified and the user just presses RETURN, LINE, or END, it 
returns the host specified by rdefault. 
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If :default is not specified or is nil, :or-nil is specified 
with a value other than nil, and the user just presses 
RETURN, LINE, or END, it returns nil. Otherwise, it returns 
the host object whose name the user types. The default 
for or-nil is nil. 

(:host-or-local :default default :or-nil or-nil) 

The same as (:host :host-type :or-local rdefault default 
:or-nil or-nil). This option is obsolete. 

(:pathname-host :default default :or-nil or-nil) 

The same as (-.host -.host- type '.pathname -.default 

default :or-nil or-nil). This option is obsolete. 

(:host-list :host-type host-type :or-nil or-nil) 

Reads a series of names of network hosts, separated by 
spaces or commas, and terminated by return, line, or end. 
:host-type has the same meaning as for the :host option. 
:host-list returns a list of the host objects whose names 
the user types, unless or-nil is not nil and the user just 
presses RETURN, LINE, or END. In that case it returns nil. 
The default for or-nil is t. 

(rkeyword :or-nil or-nil) 

Reads the name of a symbol to be interned in the 
keyword package, terminated by return, line, or END. 
The symbol name should not have a package prefix (that 
is, it should not be preceded by a colon). Lower-case 
letters in the name are converted to upper case. 
rkeyword returns the keyword symbol whose name the 
user types, unless :or-nil is specified with a value other 
than nil and the user just presses RETURN, LINE, or END. 
In that case it returns nil. The default for or-nil is nil. 

(:keyword-list :or-nil or-nil) 

Reads a series of names of symbols to be interned in the 
keyword package, separated by spaces or commas, and 
terminated by return, line, or end. The symbol names 
should not have package prefixes (that is, they should not 
be preceded by colons). Lower-case letters in the names 
are converted to upper case. :keyword-list returns a list 
of keyword symbols whose names the user types, unless 
or-nil is not nil and the user just presses return, line, or 
END. In that case it returns nil. The default for or-nil is 
t. 

(:font :or-nil or-nil) 

Reads the name of a font, terminated by RETURN, LINE, or 
END. The font name should not have a package prefix 
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(that is, it should not be preceded by fonts:), and it must 
be the name of a known font. :font returns the font (not 
the symbol) whose name the user types, unless :or-nil is 
specified with a value other than nil and the user just 
presses RETURN, line, or end. In that case it returns nil. 
The default for or-nil is nil. 

(:font-list :or-nil or-nil) 

Reads a series of names of fonts, separated by spaces or 
commas, and terminated by RETURN, LINE, or END. The 
font names should not have package prefixes (that is, they 
should not be preceded by fonts:), and they must be 
names of known fonts. :font-list returns a list of the 
fonts (not the symbols) whose names the user types, 
unless or-nil is not nil and the user just presses return, 
line, or END. In that case it returns nil. The default for 
or-nil is t. 

(robject rclass class :or-nil or-nil) 

Reads the name of an object in the network namespace, 
terminated by RETURN, line, or END. class is a keyword 
representing a namespace class or a string that is the print 
name of a class keyword. You must supply this argument. 
:object returns the namespace object whose name the 
user types, unless :or-nil is specified with a value other 
than nil and the user just presses RETURN, LINE, or END. 
In that case it returns nil. The default for or-nil is nil. 

(:object-list :class class :or-nil or-nil) 

Reads a series of names of objects in the network 
namespace, separated by spaces or commas, and terminated 
by RETURN, LINE, or END. class is a keyword representing a 
namespace class or a string that is the print name of a 
class keyword. You must supply this argument. 
:object-list returns a list of the namespace objects whose 
names the user types, unless or-nil is not nil and the user 
just presses return, line, or end. In that case it returns 
nil. The default for or-nil is t. 

(rclass :or-nil or-nil) 

Reads the name of a network namespace class, terminated 
by RETURN, LINE, or END. The name should not contain a 
package prefix (that is, it should not be preceded by a 
colon). It returns the keyword representing the class 

wnuse lieunt: uie usei tyyeo, umcoa ivri-uui is bjrxuicu witii 

a value other than nil and the user just presses RETURN, 
line, or END. In that case it returns nil. The default for 
or-nil is nil. 
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Streams are permitted to have a handler for :prompt-and-read messages. 
The prompt-and-read function first determines whether the query-io 
stream handles the :prompt-and-read message. If so, it sends a 
:prompt-and-read message with its own arguments on to the stream. The 
stream returns several values. The first value the stream returns says 
whether or not it wants to handle the interaction with the user itself. It 
returns nil to indicate that it declines to handle the message, in which case 
the prompt-and-read function continues its normal action of prompting the 
user. When the first value is not nil, the prompt-and-read function 
returns the rest of the values to its caller. 

define-prompt-and-read-type keyword parameter-list description Special Form 

&body body 
Defines a new type keyword for prompt-and-read. Defines a dispatch 
function to be called to get input from the user when prompt-and-read is 
called with a type keyword of keyword. The dispatch function is defined as 
the prompt-and-read property of keyword, which can be a symbol in any 
package. Its parameter list is derived from parameter-list , and its body is 
body, prompt-and-read returns whatever the dispatch function returns. 

If the first argument to prompt-and-read is just keyword, the dispatch 
function is called with no arguments. If the first argument to 
prompt-and-read is (keyword . type-args), the arguments to the dispatch 
function are the elements of type-args. These are a series of alternating 
keywords and values. 

parameter-list is nil if no type-args are allowed, or else a list of &key 
elements for the dispatch function's parameter list. 
define-prompt-and-read-type inserts &key in the parameter list itself; 
&key should not appear in parameter-list. 

description can be nil, a format control string, a list of a format control 
string and format control args, or a form to be evaluated, description is 
used to generate input-type in the default prompt, "Enter input-type: ": 

description input-type 

nil "a " followed by the print name of the type keyword. 

format control string 

Generated by calling format with arguments of t and the 
control string when it is time to display the prompt. 

list of format control string and args 

Generated by calling format with arguments of t, the 
control string, and the control args when it is time to 
display the prompt. The control args can examine any of 
the parameters in parameter-list. 



70 

Programming the User Interface March 1985 



form Generated by evaluating the form when it is time to 

display the prompt. The form can examine any of the 
parameters in parameter-list. It should send output to 
standard-output. 

body is the body of the dispatch function. Often the body is a call to a more 
primitive reading function, such as read or readline. It is the responsibility 
of the body or a function it calls to provide input editing if needed. 

Example: 

( def i ne-prompt-and-read-type : f 1 avor-name 

((impossible-is-ok t)) 

"the name of a flavor" 

(sys: read- flavor-name query-to impossible-is-ok)) 

sys:read-flavor-name is a function that reads a flavor name with 
completion over the set of defined flavors. 
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PART II. 



Using the Window System 
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10. Introduction to Using the Window System 



"Using the Window System" is intended to explain how you, as a programmer, can 
use the set of facilities in the Lisp Machine known collectively as the window 
system. Specifically, this document explains how to create windows, and what 
operations can be performed on them. It also explains how you can customize the 
windows you produce, by mixing together existing flavors to produce a window with 
the combination of functionality that your program requires. This document does 
not explain how to extend the window system by defining your own flavors. 

You should have a working familiarity with Symbolics-Lisp. You should also have 
some experience with the user interface of the Symbolics Lisp Machine, including the 
ways of manipulating windows, such as the [Edit Screen], [Split Screen], and 
[Create] commands from the System menu. Furthermore, you must understand 
something about flavors. While you need not be familiar with how methods are 
defined and combined, you should understand what message passing is, how it is 
used on the Lisp Machine, what a flavor is, what a "mixin" flavor is, and how to 
define a new flavor by mixing existing flavors. See the section "Flavors" in Reference 
Guide to Symbolics-Lisp, 
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11. Concepts 



11.1 Purpose of the Window System 

The term window system refers to a large body of software used to manage 
communications between programs in the Lisp Machine and the user, via the Lisp 
Machine console. The console consists of a keyboard, a mouse, and one or more 
screens. 

The window system controls the keyboard, encoding the shifting keys, interpreting 
special commands such as the function and select keys, and directing input to the 
right place. The window system also controls the mouse, tracking it on the screen, 
interpreting clicks on the buttons, and routing its effects to the right places. The 
most important part of the window system is its control of the screens, which it 
subdivides into windows so that many programs can co-exist, and even run 
simultaneously, without getting in each other's way, sharing the screens according to 
a set of established rules. 



11.2 Windows 

When you use the Lisp Machine, you can run many programs at once. You can 
have a Lisp Listener, an editor, a mail reader, and a network connection program 
(you can even have many of each of these) all running at the same time, and you 
can switch from one to the other conveniently. Interactive programs get input from 
the keyboard and the mouse, and send output to a screen. Since there is only one 
keyboard, it can only talk to one program at a time. However, each screen can be 
divided into regions, and one program can use one region while another uses another 
region. Furthermore, this division into regions can control which program the mouse 
talks to; if the mouse blinker (the thing on the screen that tracks the mouse) is in 
a region associated with a certain program, this can be interpreted as meaning that 
the mouse is talking to that program. Allowing many programs to share the input 
and output devices is the most important function of the window system. 

The regions into which the screen is divided are known as windows. In your use of 
the Lisp Machine, you have encountered windows many times. Sometimes there is 
only one window visible on the screen; for example, when you cold boot a Lisp 
Machine, it initially has only one window showing, and it is the size of the entire 
screen. If you start using the System menu's [Create], [Edit Screen], or [Split 
Screen] commands, you can make windows in various places of various sizes and 
flavors. Usually windows have a border around them (a thin black rectangle around 
the edges of the window), and they also frequently have a label in the lower left- 
hand corner or on top. This is to help the user see where all the windows are, 
what parts of the screen they are taking up, and what kind of windows they are. 
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Sometimes windows overlap; two windows may occupy some of the same space. 
While the [Split Screen] command will never do this, you can make it happen by 
creating two windows and simply placing them so that they partially overlap, by 
using [Edit Screen]. If you have never done so, you should try it. The window 
system is forced to make a choice here: Only one of those two windows can be the 
rightful owner of that piece of the screen. If both of the windows were allowed to 
use it, then they would get in each other's way. Of these two windows, only one 
can be visible at a time; the other one has to be not fully visible, but either partially 
visible or not visible at all. Only the visible window has an area of the screen to 
use. 

If you play around with this, you will see that it looks as if one window is on top of 
the other, as if they were two overlapping pieces of paper on a desk and one were 
on top. Create two Lisp Listeners using the [Create] command of the System menu 
or the [Edit Screen] menu, so that they partially overlap, and then single-click-left 
on the one that is on the bottom. It will come to the top. Now single-click-left on 
the other one; it will come back up to the top. The one on top is fully visible, and 
the other one is not. We will return to the concepts of visible and not-fully-visible 
windows later in more detail. 

From the point of view of the Lisp world, each window is a Lisp object. A window 
is an instance of some flavor of window. There are many different window flavors 
available; some of them are described in this document. 

Windows can function as streams by accepting all the messages that streams accept. 
If you do input operations on windows, they read from the keyboard; if you do 
output operations on windows, they type out characters on the screen. The value of 
terminal-io is normally a window, and so input/output functions on the Lisp 
Machine do their I/O to windows by default. 

Windows have internal state, contained in instance variables, that indicate which 
screen the window is on, where on the screen it is, where its cursor is, what 
blinkers it has, how it fits into the window hierarchy, and much more. You can get 
windows to do things by sending them messages; they accept a wide variety of 
messages, telling them to do such things as changing their position and size, writing 
characters and graphics, changing their labels and borders, changing status in 
various ways, redrawing themselves, and much more. The main business of this 
document is to explain the meaning of the internal state of windows, and to explain 
what messages you can send and what those messages do. 



11.3 Hierarchy of Windows 

Several Lisp Machine system programs and application programs present the user 
with a window that is split up into several sections, which are usually called window 
panes or panes. For example, the Inspector has six panes in its default 
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configuration: the one you type forms into at the top, the menu, the history list, 
and the three inspection panes below the first three. The window Debugger and 
Zmail also use elaborate windows with panes. These panes are not exactly the same 
as the other windows we have discussed, because instead of serving to split up the 
screen, they serve to split up the program's window itself. Sometimes you don't see 
this, because often the program's window is taking up the whole screen itself. Try 
going into the [Edit Screen] system and reshaping a whole Inspector or Zmail 
window. You will see that the panes serve to divide this window up into smaller 
areas. 

In fact, the same window system functionality is used to split up a paned window 
into panes as is used to split up a screen into windows. Each pane is, in fact, a 
window in its own right. Windows are arranged in a hierarchy, each window having 
a superior and a list of inferiors. Usually the top of the hierarchy is a screen. In 
the example above, the Inspector window is an inferior of the screen, and the panes 
of the window are inferiors of the Inspector window. The screen itself has no 
superior (if you were to ask for its superior, you would get nil). 

The position of a window is remembered in terms of its relative position with respect 
to the its superior; that is, what we remember about each window is where it is 
within its superior. To figure out where a window is on the screen, we add this 
relative position to the absolute position of the superior (which is computed the same 
way, recursively; the recursion terminates when we finally get to a screen). The 
important thing about this is that when a superior window is moved, all its inferiors 
are moved the same amount; they keep their relative position within the superior 
the same. You can see this if you play with the [Move Window] command in [Edit 
Screen]. 

One effect of the hierarchical arrangement is that you can use [Edit Screen] to edit 
the configuration of panes in a frame as well as to edit the configuration of windows 
on the screen, by clicking right on [Edit Screen]. If you have ever clicked right on 
[Edit Screen] while the mouse was on top of a window with inferiors, such as an 
editor, you will have noticed that you get a menu asking which of these two things 
you want to do. In fact, that menu can have more than two items; the number of 
items grows as the height of the hierarchy. 

So, what [Edit Screen] really does is to manipulate a set of inferiors of some specific 
superior window, which may or may not be a screen. The set of inferiors that you 
are manipulating is called the active inferiors set; each inferior in this set is said to 
be active. Windows can be activated and deactivated. The active inferiors are all 
fighting it out for a chance to be visible on their superior. If no two active inferiors 
overlap, there is no problem; they can all be uncovered. However, whenever two 
overlap, only one of them can be on top. [Edit Screen] lets you change which active 
inferiors get to be on top. There is also a part of the window system called the 
screen manager whose basic job is to keep this competition straight. For example, it 
notices that a window that used to be covering up part of a second window has been 
reshaped, and so the second window is no longer covered and can be brought to the 
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top. Inactive windows are never visible until they become active; when a window is 
inactive, it is out of the picture altogether. For more on the screen manager: See 
the section "The Screen Manager", page 86. 

Each superior window keeps track of all of its active inferiors, and each inferior 
window keeps track of its superior, in internal state variables. Superior windows do 
not keep track of their inactive inferiors; this is a purposeful design decision, in order 
to allow unused windows to be reclaimed by the garbage collector. So, when a 
window is deactivated, the window system doesn't touch it until it is activated again. 



11.4 Pixels and Bit-save Arrays 

A screen displays an array of pixels. Each pixel is a little dot of some brightness 
and color; a screen displays a big array of these dots to form a picture. On regular 
black-and-white screens, each pixel can have only two values: lit up, and not lit up. 
The way the display of pixels is produced is that inside the Lisp Machine, there is a 
special memory associated with each physical screen that has some number of bits 
assigned to each pixel of the screen; those bits say, for each pixel, what brightness 
and color it should display. For regular black-and-white screens, since a pixel can 
have only two values, only a single bit is stored for each pixel. If the bit is a one, 
the pixel is not lit up; if it is a zero, the pixel is lit up. (Actually, this sense can be 
inverted if you want.) Everything you see on the screen, including borders, graphics, 
characters, and blinkers, is made up out of pixels. 

When a window is fully visible, its contents are displayed on a screen so that they 
can be seen. What happens to the contents when the window ceases to be fully 
visible? There are two possibilities. A window may have a bit-save array. A bit- 
save array is a Lisp array in which the contents of the window can be saved away 
when the window loses its visibility; if a window has a bit-save array, then the 
window system will copy its contents out of the screen and into the bit-save array 
when the window ceases to be fully visible. If the window does not have a bit-save 
array, then there is no place to put the bits, and they are lost. When the window 
becomes visible again, if there is a bit-save array, the window system will copy the 
contents out of the bit-save array and back onto the screen. If there is no bit-save 
array, the window will try to redraw its contents; that is, to regenerate the contents 
from some state information in the window. Some windows can do this; for 
example, editor windows can regenerate their contents by looking at the editor 
buffer they are displaying. Lisp Listener windows cannot regenerate their contents, 
since they do not remember what has been typed on them. In lieu of regenerating 
their contents, such windows just leave their contents blank, except for the 
decorations in the margins of the window, which thev are able to regenerate. 

The advantage of having a bit-save array is that losing and regaining visibility does 
not require the contents to be regenerated; this is desirable since regeneration may 
be computationally expensive, or even impossible. The disadvantage is that the bit- 
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save array uses up storage in the Lisp world, and since it can be pretty big, it may 
need to be paged in from the disk in order to be referenced (depending on how hard 
the virtual memory system is being strained). If the paging overhead for the bit- 
save array is very high, it might have been faster not to have one in the first place 
(although the system goes through some special trouble to try to keep the bit-array 
out of main memory when it is not being used). 

The other important use of bit-save arrays is for windows that have inferiors. If the 
superior window is not visible, the inferiors can use the bit-save array of the superior 
as if it were a screen, and they can draw on it and become exposed on it. See the 
section "Screen Arrays and Exposure", page 79. 

An additional benefit of having a bit-save array is that the screen manager can do 
useful things for partially visible windows when those windows have bit-save arrays; 
at certain times it can copy some of the pixels from the bit-save array onto the part 
of the screen in which the window is partially visible, so that when a window is only 
partially visible, you can see whatever part is visible. See the section "The Screen 
Manager", page 86. 



11.5 Screen Arrays and Exposure 

This section discusses the concepts of screen arrays and of exposed windows. These 
have to do with how the system decides where to put a window's contents (its 
pixels), how the notion of visibility on the screen is extended into a hierarchy of 
windows, and how this interacts with the desire of a program or of the user to have 
some windows visible and other windows not visible at a particular time. These are 
complex concepts, which you don't have to understand completely to make use of the 
window system. You probably do need to understand these ideas thoroughly only if 
you plan to make advanced use of the window system, such as creating your own 
frame or customizing very basic aspects of the system's behavior. 

The following discussion attempts to explain what it means for a window to be 
exposed. It will be necessary for us to refer to the concept of a window being 
exposed before we explain exactly what that means. For the time being, the 
approximate meaning of "exposed" is that a window is exposed if it has somewhere 
for its typeout to go. A window that is fully visible on a screen is exposed, because 
its typeout can go on the screen. A window might be exposed even if it is not fully 
visible, because its typeout might be able to go to a bit-save array somewhere. 

Each window has in it a set of all those inferiors that are "ready to be exposed". 
This set is a subset of the set of active inferiors, discussed above. When you send a 
window an :expose message, it becomes "ready to be exposed" and is added to the 
set; when you send a window a rdeexpose message, it ceases being ready to be 
exposed and is removed from the set. These are the only ways anything ever gets 
into or out of the set. The meaning of "ready" to be exposed will be cleared up 
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soon; for the time being, we will just say that either all the windows on that list 
are, in fact, exposed, or else none of them are exposed but they are all still "ready" 
to become exposed. 

Each window has an internal state variable called its screen-array. The value of the 
screen-array variable is where output to the window should go; if a program draws a 
character "on a window" or draws a triangle "on a window", that means it is 
changing the values of pixels in the window's screen-array. The value of the screen- 
array variable is used in figuring out whether a window is exposed. 

The screen-array of a screen (remember, a screen is a window itself) is the special 
memory that gets displayed on the physical screen. For any other window, if the 
window is exposed, then its screen-array is an indirect array that points into a 
section of the superior's screen-array; namely, it points into the area of the 
superior's screen-array where the inferior gets displayed on the superior. For 
example, consider a window whose superior is a screen, which is exposed, and whose 
upper-left-hand corner is at location (100,100) in the screen. Then the window's 
screen-array would be an indirect array whose (0,0) element is the same as the 
(100,100) element of the screen. If you were to set a pixel in the window's screen- 
array, the corresponding pixel in the screen (found by adding 100 to each coordinate) 
would be set to that value. 

What happens to the screen-array variable if the window is not exposed? That 
depends on whether the window has a bit-save array or not. If there is a bit-save 
array, then the screen-array becomes the bit-save array. If there is no bit-save 
array, the screen-array becomes nil. 

The most important thing to understand about the value of screen-array is that it is 
defined recursively, in terms of the superior's screen-array. Consider a window 
which is exposed, and all of whose ancestors are exposed: The superior is exposed, 
the superior's superior is exposed, and so on all the way back to the screen. Then 
each window has a screen-array that points into the middle of its superior's screen- 
array, all the way up the hierarchy, through the window whose screen-array points 
into the middle of the screen. When typeout is done on the window, it will appear 
on the screen, offset by the combined offsets of all the superiors, so that it will 
appear in the correct absolute position on the screen. 

Now, suppose one of those ancestors becomes deexposed. There are two alternative 
things that might happen. First, consider the case in which that ancestor (the one 
that got deexposed) has a bit-save array. That ancestor's screen-array will no longer 
point to its own superior; its screen-array will be its bit-save array. That means 
that our window's screen-array will be pointing, perhaps through several levels of 
indirection, into that ancestor's bit-save array. The ancestor window is not exposed, 
but our window is still exposed. If typeout is done on our window, it will appear on 
the bit-save array of the ancestor. This won't actually be visible to the user, since it 
is only a bit-save array and not an actual screen, but the typeout can proceed and 
the bits can be drawn into the bit-save array. Later, if and when the ancestor is 
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exposed again, the window system will copy the bit-save array onto the screen, and 
the drawing that had been done will become visible. 

There is another case: Suppose the ancestor is deexposed, and it does not have a 
bit-save array. Then the ancestor's screen-array becomes nil. Well, now we have a 
problem. The ancestor's inferior is exposed, and so its screen-array is supposed to 
point into the screen-array of its superior. However, there is no way to point into 
the middle of a nil. There just isn't anywhere for the screen-array to point to; the 
window doesn't have anywhere to type out. Since it has nowhere to type out, it 
gets deexposed too. In general: When a window is deexposed, and it has no bit-save 
array, all of its inferiors that are ready to be exposed (all of which are, in fact, 
exposed) become deexposed. They continue to be "ready to be exposed", though. 

In fact, this is the distinction between "ready to be exposed" and actually being 
exposed. The rule is: A window is exposed when and only when it is "ready to be 
exposed" and its superior has a screen-array. That is what "exposed" means. 

When a window is sent an :expose message, it always becomes "ready to be 
exposed". If the superior has a screen-array, then it immediately becomes exposed. 
If the superior does not have a screen array, then the window just stays "ready", 
and when the window's superior finally gets its screen array, the window itself is 
exposed. If a window is "ready to be exposed" but is not exposed yet, then it is 
waiting for its superior to acquire a screen-array; when the superior gets one, the 
window becomes exposed. The usual way that the superior gets a screen array is 
for it to get exposed itself; when this happens, the inferiors that are "ready to be 
exposed" will all get exposed. 

Also, if the superior has no screen-array then obviously it has no bit-save array; it 
can be given one by the :set-save-bits message, which can change a window that 
doesn't have a bit-save array into a window that does have a bit-save array. You 
can dynamically change which windows have and don't have bit-save arrays, and 
windows that are affected will be exposed and deexposed accordingly. This is much 
less common, though; usually whether a window has a bit-save array or not is 
specified when the window is created, and it doesn't change. 

So, the important point is that when a window is sent an rexpose message, it may 
not become exposed then and there. If the superior has a screen-array, then the 
window will be exposed immediately. But if the superior does not have a screen 
array, then making the window exposed is delayed until the superior acquires a 
screen array. When the superior gets its screen array, then the window itself 
becomes exposed. So what the :expose always does is to add the window to the set 
of windows that are "ready to be exposed"; a window is exposed precisely when it is 
"ready to be exposed" and the window's superior has a screen-array. The 
rdeexpose message always removes a window from the set of windows "ready to be 
exposed", and therefore is always stops the window from being exposed. 

Note well that "exposed" does not mean "visible". A window can be exposed by 
virtue of being able to type out on a bit-save array, and not be visible at all. A 
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window is fully visible if and only if all its ancestors are exposed, and the top level 
ancestor is a screen. 

(A detail: If a window is top-level (if it has no superior) then it is as if "its superior 
has a screen array"; sending a top-level window an rexpose message always exposes 
it immediately. You usually don't deexpose top-level windows anyway.) 

(Another detail: It is possible for a screen to be deexposed. In particular, if a Lisp 
Machine does not have a color display physically attached to it, there is still a "color 
screen" Lisp object in the Lisp world, but it is deexposed (and so are all its inferiors). 
This is so saved Lisp environments can be moved easily between machines with 
different hardware configurations. The screen object is left deexposed so that 
programs will not try to output to it.) 

In order to maintain the model that windows are like pieces of paper on a desk, it is 
important that no two windows that both occupy some piece of screen space be 
exposed at the same time. To make sure that this is true, whenever a window 
becomes exposed, the system deexposes any of its exposed siblings that it overlaps. 
(Note: This is not true for temporary windows). 

The window system uses conformal indirect arrays for its screen arrays. This means 
that on 3600-family-computers the bit-array in which a window saves its bits when it 
is not visible does not have to be the full width of the screen; it is just the width of 
the window, rounded up to the next multiple of 32 bits. Screen arrays do not use 
multilevel indirection; the screen array of a nonscreen sheet always indirects either 
to a bit-save array or to the screen array of its screen. The screen array of a screen 
is always a displaced array to the hardware screen buffer. 



11.6 Window Exposure and Output 

The main reason for worrying about whether a window is exposed or not is in order 
to figure out whether it should be allowed to type out. If a window is not exposed, 
either its superior has no screen-array (so there is no place for its output to go), or 
it is not ready to be exposed at all (so it is supposed to be hidden). Normally, when 
a process tries to do output to a window that is not exposed, by sending stream 
messages (such as :tyo and :string-out), the process waits in a state called 
Output Hold; the process continues to wait until the window becomes exposed 
again, at which time it proceeds with its typeout. The term "typeout" refers not 
only to character output, but to any form of modification of the window's contents, 
including drawing of graphics. 

This is the normal case that you run into most of the time. However, there are 
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A process trying to output to a window does not actually decide to wait in the 
Output Hold state based on whether or not the window is exposed. There is 
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actually a flag in each window, called the output hold flag, that is really being 
checked to see whether output can go ahead. The output hold flag is cleared when 
the window is exposed and set when the window is deexposed, and output is held 
when this flag is set. The complexity comes from other things besides exposing that 
clear this flag. 

When a process attempts to type out on a window which is deexposed and has its 
output hold flag set, what happens depends on the window's deexposed typeout 
action. The deexposed typeout action can be any of certain keyword symbols, or it 
can be a list; it indicates an action that should be taken when there is an attempt 
to type out to a deexposed window. After the action is taken, if the output hold flag 
is still set, the process will wait for it to clear. The interesting thing is that the 
action may affect the value of the output hold flag. 

By default, the deexposed typeout action is rnormal, which means that no special 
action should be taken; hence the process will wait for the window to become 
exposed. 

If the deexposed typeout action is texpose, however, then the action will be to send 
the window an :expose message. This may expose the window (if the superior has 
a screen-array), and if it does expose the window then the output hold flag will be 
cleared and typeout will be able to proceed immediately. If the superior is the 
screen, the rexpose option provides a very different user interface from the rnormal 
option. 

If the deexposed typeout action is rpermit, that means that typeout should be 
permitted even though the window is not exposed, as long as the window has a 
screen array; that is, it may type out on its own bit-save array even though it is not 
exposed. The next time the window is exposed the updated contents will be 
retrieved from the bit-save array. The action for :permit is to turn off the output 
hold flag if the window has a screen array. This mode has the disadvantage that 
output can appear on the window without anything being visible to the user, who 
might never see what is going on, and might miss something interesting. 

The deexposed typeout action may also be motify, which means that the user 
should be notified when there is an attempt to do output on the window. The 
action taken is to send the motice message to the window with the argument 
routput. The default response to this is to notify the user that the window wants 
to type out and to make the window "interesting" so that function s can select it. 
Windows in the Terminal program have motify deexposed typeout action by default. 

Another permissible value is rerror, which means that an error should be signalled. 

If the deexposed typeout action is not any of these keywords, then it should be a 
list; the action will be to send the message specified by the first element of the list 
to the window, passing the rest of the elements of the list as arguments. 

There is another exception to the rule that you can only type out on exposed 
windows: The special form tv:sheet-force-access allows you to do typeout on a 
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window that has a screen array even if its output hold flag is set. Note that the 
screen array must be this window's bit-save array (since the window is not exposed). 
What tv:sheet-force-access does is to temporarily turn off the output hold flag 
while executing its body. This is useful for drawing things on a window while the 
window is not visible on the screen. It is better to do it this way than to use a 
deexposed typeout action of :permit, in most cases, since the effect of 
tv:sheet-force-access is local to the program, while the deexposed typeout action 
affects anything that types out on the window. If the window does not have a 
screen-array, tv:sheet-force-access doesn't do anything at all; it just returns 
without evaluating its body. 

Another way that typeout can be held up is if the window is locked. Locking is 
independent of the output hold flag and is not affected by the deexposed typeout 
action or by tv:sheet-force-access. There are two ways that a window can be 
locked. The normal form of locking is a mutual exclusion that guarantees that only 
one process at a time operates on the window's contents and attributes. If one 
process is working on the window and another tries to do so, the second process will 
wait until the first one is finished. In the absence of program bugs, this wait is for 
a very short time and should not be noticeable. 

The other form of locking is called temp-locking. If a window is temp-locked, then 
any attempt to type out on it will wait, regardless of everything else. Temp-locking 
has to do with temporary windows: See the section "Temporary Windows", page 84. 

tv:sheet-force-access (sheet don't-prepare-sheet) body... Special Form 

Allows typeout on sheet if it has a screen array (that is, if it is exposed or 
has a bit-save array). If don't-prepare-sheet is nil, prepares the sheet before 
executing body. If sheet does not have a screen array, tv:sheet-force-access 
just returns without executing body. Use this to put output onto a 
deexposed window that has a bit-save array. 

tv:prepare-sheet (sheet) body... Special Form 

Prepares sheet for input or output. Ensures that sheet is not locked or in 
output-hold. Opens blinkers on inferiors and exposed superiors. 



11.7 Temporary Windows 

Normally, when a window is exposed in an area of the screen where there are 
already some other exposed windows, the windows that used to be there are 
deexposed automatically by the window system. This is because the window system 
normally doesn't leave two windows both exposed if they overlap. (In the absence of 

overlapping windows to both be exposed.) 

But sometimes there are windows that only get put up on the screen for a very 
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short time. The most obvious examples of such windows are the momentary menus 
that only appear for long enough for you to select an item. It would be unfortunate 
if every time a momentary menu appeared, the windows under it had to be 
deexposed. The ones without bit-save arrays would have their screen image 
destroyed, forcing them to regenerate it or to reappear empty. The ones with bit- 
save arrays would not be damaged in this way, but they would have to be deexposed, 
and deexposure is a relatively expensive operation. 

This problem is solved for momentary menus by making them out of temporary 
windows. In general, when you create a window, you can specify that you want it 
to be a temporary window. Temporary windows work differently from other 
windows in the following way: When a temporary window is exposed, it saves away 
the pixels that it covers up. It restores these pixels when it is deexposed. These 
pixels may come from several different windows. This way it doesn't mess up the 
area of the screen that it uses, even if it covers up some windows that don't have 
bit-save arrays. 

Also, a temporary window, unlike a normal window, does not deexpose the windows 
that it covers up. This way the covered windows need not try to save their bits 
away in their bit-save arrays (if they have them) or ever have to try to regenerate 
their contents (if they don't). They never notice that the temporary window was 
(temporarily) there. 

There would be some problems if temporary windows were this simple. Suppose 
there is a normal window, and a temporary window has appeared over it; some of 
the contents of the normal window are being saved in an array inside the temporary 
window. Now, if the normal window is moved somewhere else, and possibly becomes 
deexposed or is overlapped by other windows or something, and then the temporary 
window is deexposed, the temporary window will dump back its saved bits where the 
normal window used to be, even though the normal window isn't there any more, 
and so some innocent bystander will be clobbered. Furthermore, suppose typeout 
were done on the normal window; we have not deexposed it, so nothing would 
prevent the typeout from overwriting the temporary window, nor prevent the 
typeout from being overwritten in return when the temporary window is deexposed. 
Because of problems like these, when a temporary window gets exposed on top of 
some other windows, all the windows that it covers up (fully or partially) are 
temp-locked. When a window is temp-locked, any attempt to type out on it will wait 
until it is no longer temp-locked. Furthermore, any attempt to deexpose, deactivate, 
move, or reposition a temp-locked window will wait until the window is no longer 
temp-locked. 

Because of temp-locking, you should never write a program that will put a temporary 
window up on the screen for a "long" time. There should be some action by the 
user, such as moving the mouse, which will make the temporary window deexpose 
itself. It is best if any attempt by the user to get the system to do something 
makes the temporary window go away. While the temporary window is in place, it 
blocks many important window system operations over its area of the screen. The 
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windows it covers cannot be manipulated, and programs that try to manipulate them 
will end up waiting until the temporary window goes away. Temporary windows 
should only be used when you want the user to see something for a little while and 
then have the window disappear. The temp-locking is undone when the temporary 
window is deexposed. 

It works fine to have two or more temporary windows exposed at a time. If you 
expose temporary window a and then expose temporary window b, and they don't 
overlap each other, they can be deexposed in either order, and any windows that 
both of them cover up will be temp-locked until both of them are deexposed. If b 
covers up a, then a will be temp-locked just like any other window, and so it will 
not be possible to deexpose a until b has been deexposed. 



11.8 The Screen Manager 

The screen manager is a subsystem of the window system that does various 
background jobs involved with keeping things straight in the window system. It has 
several responsibilities. One job of the screen manager is to find any window that is 
active and deexposed, but not covered up by any windows. There is no reason for 
such a window not to be exposed, so the screen manager exposes it. This is called 
autoexposure. 

Another job of the screen manager is to manage those parts of the screen that are 
not currently part of any exposed window. When you first start using the Lisp 
Machine, the entire screen is covered by a big Lisp Listener window, and the initially 
created windows for Zmacs, Zmail, and so on, are all as large as the entire screen, so 
this issue does not arise. Similarly, if you use [Split Screen] to divide the screen up 
into windows, the windows will use up all of the area of the screen. However, if you 
use the [Create] or [Edit Screen] commands, you can make windows of arbitrary 
shapes and sizes, and you can leave parts of the screen where there is no exposed 
window. 

When the screen manager sees that there is such an area of the screen, it considers 
all of the active windows that aren't exposed. If it finds such a window, and that 
windows has a bit-save array, then the screen manager displays the contents of the 
bit-save array for the corresponding portion of the screen. This gives the visual 
impression of overlapping pieces of paper on a desktop; the deexposed window is 
partially covered up by the exposed windows, but you can still see those parts that 
aren't covered. 

If there is more than one active deexposed window that might be displayed in a 
given area of the screen, then the screen manager uses its priority ordering to decide 
which one to display. 

Usually the screen manager only displays partially visible windows that have bit-save 
arrays. But if you want to make a window that doesn't have a bit-save array and 
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you want the screen manager to try to display it when it is only partially exposed, 
use the following mixin: 

tv:show-partially-visible-mixin Flavor 

If a window has this flavor mixed in, then the screen manager will attempt 
to show it to the user when it is partially visible even if it doesn't have a bit- 
save array. The screen manager cannot display the contents of the window, 
since there is no bit-save array to hold them, but it does give the window a 
screen array temporarily, tells it to refresh itself, and then shows whatever 
the window displays. Often this means that you will see the label and 
borders of the window, but no contents. 

The screen manager not only manages screens; it can manage any window that has 
inferiors. Windows with panes are split up into windows just the same way screens 
are split up into windows, and so the screen manager can do the same thing to 
panes of paned windows that it does with windows directly on screens. The action 
of the screen manager on the inferiors of a window is controlled by that window's 
response to the rscreen-manage message; the default is to do screen management 
in the same way as it is done on a screen. 

tv:no-screen-managing-mixin Flavor 

Prevents the screen manager from dealing with the inferiors of a window. 

Suppose there is a section of the screen in which there are no exposed windows, and 
more than one active, deexposed window could be exposed to fill this area, but the 
two could not both be exposed (because they overlap). Which one gets to be 
exposed? Here's another issue: When the screen manager wants to display pieces of 
partially visible windows, there might be more than one deexposed window that 
might be displayed in a given area of the screen. Somehow the screen manager 
must decide which window to display. 

The way it decides is on the basis of a priority ordering. All of the active inferiors of 
a window are maintained in a specific order, from highest to lowest priority. When 
there is a section of the screen on which more than one active inferior might be 
displayed, the inferior that is earliest in the ordering, and so has the highest 
priority, is the one that gets displayed. This ordering is like the relative heights of 
pieces of paper on a desk; the highest piece of paper at any point on the desk is the 
one that you see, and all the rest are covered up. 

The screen manager has a somewhat complicated algorithm for keeping track of this 
ordering. Part of the algorithm involves a value kept for each window called its 
priority > which may be a fixnum or nil. The general idea is that windows with 
higher numerical priority values have higher priority to appear on the screen. If a 
window has priority nil, then its priority is less than that of any window with 
numerical priority; that is, nil acts like the lowest possible number. The default 
value for priority is nil. 
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The ordering itself is not based on just the priorities. Instead, the way it works is 
that the ordering is remembered, and at various times, the windows are resorted 
according to the following set of rules: 

1. Exposed windows go in front of nonexposed windows. 

2. If two windows are both exposed or both have the same value of priority, their 
order is not changed by the sorting. 

3. If two nonexposed windows have different values of priority, then the one with 
the higher value goes in front of the one with the lower value. 

So not only the priority values make a difference; the relative positions of windows 
before the resorting matters too. 

The resorting happens whenever some event occurs that might change the ordering. 
For example, when a window is exposed or deexposed, or when a window's priority 
changes, the ordering it is on must be resorted. Note that the sort is stable; that is, 
if we don't have any preference for one window over another then they keep their 
previous ordering. Since most of the time numerical priorities are not used anyway 
(the priorities of most windows are nil), this is generally what determines the 
ordering. When a window is exposed, it gets pulled up to the front of the ordering, 
and then as other windows later get exposed on top of it, it sinks back down. More 
recently exposed windows will be closer to the front. 

There is also an operation called burying a window, which first deexposes the 
window, then moves it to the end of the ordering, and finally (since something 
interesting has happened) causes the ordering to be resorted. So burying a window 
essentially makes it be the farthest from the front of the ordering of all windows 
with the same priority as it. A program usually buries its window when it thinks 
that the user is not interested in that window and would prefer to see some other 
windows. The [Bury] command in [Edit Screen] is a way for the user to bury a 
window. 

Negative priorities have a special meaning. If the value of a window's priority is -1, 
then the window will not ever be visible at all even if it is only partially covered; 
however, it will still get autoexposed. If the value of priority is -2 or less, then the 
window will not even be autoexposed, and so it will simply not become exposed 
unless sent an explicit :expose message. 

(Another minor point: Windows whose area of the screen does not lie within the 
boundaries of their superior cannot be exposed at all, and so the screen manager 
does not try to autoexpose such windows. However, they can be partially visible.) 
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send a rdeexpose message to an exposed window. The window is no longer 
exposed, but since it is closer to the front of the ordering, and especially if numerical 
priorities are not being used much, then it may end up being the foremost window 
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in the ordering that occupies its area of the superior, and so autoexposure is likely to 
expose it again immediately! If you want to do a series of deexposing and exposing 
operations, they can get messed up this way by the screen manager. In order to 
prevent this from happening, you can use the tv:delaying-screen-management 
special form to delay the actions of the screen manager until all of your operations 
have been done. In simple applications, you should not need to send your own 
rdeexpose messages anyway (most deexposure is done automatically when new 
windows are exposed), and you should not need tv:delaying-screen-management; 
explicit deexposure and delaying of screen management is mostly used in advanced 
applications, and if you use these for something simple then you are probably doing 
something wrong. 

While screen management is delayed, notes to the screen manager telling what areas 
of the screen have been played with are put on a queue. When the 
tv:delaying-screen-management form is returned from, all of the entries on the 
queue are examined, and the screen manager figures out all the things that need to 
be done and does them all at once. So, by delaying screen management, you 
prevent the screen manager from seeing various intermediate states and doing 
unnecessary work, which would consume computation time and make the windows 
on the screen visibly undergo unnecessary contortions. 

When a tv:delaying-screen-management form is exited, normally or abnormally 
(that is, thrown through), the screen manager tries to run and empty the queue, 
using an unwind-protect. However, under some circumstances it cannot do screen 
management at this time. In these cases, it leaves the requests on the queue. 
There is a background process that runs all the time, called 
Screen Manager Background, that wakes up to do the screen management that 
these queue entries specify, when screen management stops being delayed. So the 
screen management does eventually happen, when the special form is exited and the 
background process wakes up. When tvtdelaying-screen-management forms are 
nested, only the outermost one will do any screen management when it is exited. 

tv:delaying-screen-management Special Form 

The tv:delaying-screen-management special form just has a body: 

( tv : del ay i ng-screen-management 
form-1 
form-2 

The forms are evaluated sequentially with screen management delayed. The 
value of the last form is returned. 

This background process has another useful function, which is optional. Recall that 
if a window has its deexposed typeout action set to rpermit, processes can type out 
on the window, but the typeout goes to the bit-save array rather than to the screen. 
The screen manager background process can be told to find any such windows on 
which some typeout has happened, and copy their partially visible parts to the screen 
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so that they can be seen. This way, you get to see the typeout that happens on 
the part of the window that isn't being covered by any other windows. 

tv:screen-manage-update-permitted-windows Variable 

This variable controls whether the screen manager looks for partially visible 
windows with deexposed typeout actions of :permit and updates the visible 
portion of their contents on the screen. If the value is nil, which it is 
initially, the screen manager does not do this. Otherwise the value should be 
the interval between screen updates, in 60ths of a second. 

The screen manager also has another job. At the same time that it does 
autoexposing, it can also select a window if there isn't any selected window at the 
time. 

The screen manager has a facility for graying areas of the screen that contain no 
windows or windows that are not fully exposed. See the section "Window Graying", 
page 90. 



11.9 Window Graying 

Screens and frames can gray areas that contain no windows or that contain 
windows that are not fully exposed. To gray an area of the screen is to cover it 
with a semitransparent texture pattern. There are two kinds of graying: 

• Background gray is used to fill in areas of the screen that don't contain any 
windows. Normally this is just the borders around the screen, but if you 
reshape all the full-screen windows to be smaller, so that there is some area of 
the screen that doesn't have a window on it, the background gray appears 
there, also. The background gray in the two areas (the part of the screen 
where you can put windows and the part of the screen where you cannot put 
windows) joins smoothly. 

• Deexposed gray is used to fill in the visible portion of a window that is not 
fully exposed. It tells you that you aren't seeing all of this window, because 
another window is covering part of it. Deexposed graying does not occur when 
a window is covered by a temporary window (like a momentary menu) because 
such a window isn't considered to be really deexposed and is often still a focus 
of the user's attention. 

These concepts generalize to any window that has inferiors, not just the screen. 
You can make a flavor of frame that fills in any empty spots with gray or grays over 
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Both kinds of graying are implemented by the screen manager, but affected by 
messages to the screen and to the deexposed windows. 
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To disable both background and deexposed gray on the main screen: 

( tv:set-screen-background-gray nil) 
(tv:set-screen-deexposed-gray nil) 

To get a light gray on both unused areas and deexposed windows: 

(tv: set-screen-background-gray tv:6X-gray) 
(tv:set-screen-deexposed-gray tv:6%-gray) 

To get a light gray over deexposed windows and a darker gray in the background: 

(tv:set-screen-background-gray tv:33X-gray) 
(tv:set-screen-deexposed-gray tv:6X-gray) 

11.9.1 Window Graying Specifications 

A graying specification determines what pattern to use in graying areas of the 
screen that contain no windows or that contain windows that are not fully exposed. 
These specifications are used as arguments to functions and messages that deal with 
graying. See the section "Functions, Flavors, and Messages for Window Graying", 
page 92. 

Following are the possible values of a specification and their meanings: 

nil Disable graying. Background gray is white (in black-on-white 

mode); deexposed gray is completely transparent. 

Two-dimensional bit array 

A stipple pattern to be replicated by bitblt. 

:white Opaque white. 

rblack Opaque black. 

Instance An object that must handle the :draw-blank-rectangle message 

to draw a gray rectangle. 

Function A function to be called with standard arguments to draw a gray 

rectangle. 

List The first element is a function to be called, and the remaining 

elements are arguments to the function to be supplied after the 
standard arguments. 

Following are the arguments to the :draw-blank-rectangle message and to a 
function to be called: 

x-size Horizontal size of the rectangle in pixels. 

y-size Vertical size of the rectangle in pixels. 

x-pos X-position of the top left corner of the rectangle on sheet. 

y-pos Y-position of the top left corner of the rectangle on sheet. 
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x-phase Starting x-coordinate of the source array. 

y-phase Starting y-coordinate of the source array. 

alu Alu function for drawing the rectangle. 

sheet Sheet or array on which to draw the rectangle. 

The variable tv:*gray-arrays* contains a list of variables that are bound to available 
predefined graying specifications. 

tv:*gray-arrays* Variable 

A list of variables bound to predefined graying specifications. You can use 
one of these as the source of a pattern for background or deexposed window 
graying. You can also make your own graying specifications and add them to 
this list. See the section "Window Graying Specifications", page 91. 

11.9.2 Functions, Flavors, and Messages for Window Graying 

tv:set-screen-background-gray gray &optional {screen Function 

tvrmain-screen) 

Specifies what pattern should be used to gray areas of a screen or frame that 
contain no windows, gray is a graying specification: See the section 
"Window Graying Specifications", page 91. Give an argument of nil to disable 
graying. 

screen can be a screen or frame. It defaults to the main monochrome screen. 

tv:set-screen-deexposed-gray gray &optional {screen Function 

tv:main-screen) 

Specifies what pattern should be used to gray areas of a screen or frame that 
contain windows that are not fully exposed, gray is a graying specification: 
See the section "Window Graying Specifications", page 91. Give an argument 
of nil to disable graying. 

screen can be a screen or frame. It defaults to the main monochrome screen. 

:screen-manage-deexposed-gray-array Message 

The screen manager sends this message to deexposed windows to give them 
an opportunity to override the kind of graying that their superior (or the 
screen) wants to provide. This message should return two values. Following 
are the possible pairs of values and their meanings: 

graying specification and nil 

Use graying specification to gray the window. 

nil and nil Let the superior decide how to gray the window. 

nil and t Disable graying of the window. 
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See the section "Window Graying Specifications", page 91. 

tv:gray-unused-areas-mixin Flavor 

This flavor, mixed into a screen or a frame, gives it the ability to gray areas 
within it that contain no windows. 

:gray-array-for-unused-areas gray (for Init Option 

tv:gray-unused-areas-mixin) 

Specifies gray as the graying specification to use in graying areas of this 
screen or frame that contain no windows. See the section "Window Graying 
Specifications", page 91. 

rgray-array-for-unused-areas of tv:gray-unused-areas-mixin Method 

Returns the graying specification that this frame or window uses in graying 
areas that contain no windows. See the section "Window Graying 
Specifications", page 91. 

:set-gray-array-for-unused-areas gray of Method 

tvtgray-unused-areas-mixin 

Sets gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying 
Specifications", page 91. 

tv:gray-deexposed-inferiors-mixin Flavor 

This flavor, mixed into a screen or a frame, gives it the ability to gray areas 
within it that contain windows that are not fully exposed. 

:gray-array-for-inferiors gray (for Init Option 

tvrgray-deexposed-inferiors-mixin) 

Specifies gray as the graying specification to use in graying areas of this 
screen or frame that contain no windows. See the section "Window Graying 
Specifications", page 91. 

:gray-array-for-inferiors of tv:gray-deexposed-inferiors-mixin Method 

Returns the graying specification that this frame or window uses in graying 
areas that contain no windows. See the section "Window Graying 
Specifications", page 91. 

:set-gray-array-for-inferiors gray of Method 

tv:gray-deexposed-inferiors-mixin 

Sets gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying 
Specifications", page 91. 
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11.10 Windows and Processes 

tv:process-mbrin Flavor 

Creates a new process associated with each window of the dependent flavor. 

:process (initial-function . options) (for tv:process-mixin) Init Option 

options are options to make-process. 



11.11 Activities and Window Selection 

11.11.1 The Selected Window and the Selected Activity 

When you type characters on the keyboard, they must be directed to some window. 
The window that receives keyboard input is the selected window. No more than one 
window can be selected at a time. Sometimes no window is selected, but usually 
this is a brief transitional state. 

tv:selected-window Variable 

The value of this variable is the currently selected window. 

tv:cold-load-stream-old-selected-window Variable 

At a cold-load-stream break, the value of this variable is the value of 
tv:selected-window at the time you entered the cold-load stream. 

A window is selectable only if it has tv:select-mixin and tv:stream-mixin as 
components. tv:select-mixin allows the window to handle messages that select it. 
tvrstream-mixin provides the window an I/O buffer, which accumulates keyboard 
characters, and lets the window handle messages to get input. tv:stream-mixin 
also provides the window with input editing. When input editing is enabled and a 
reading function tries to get input from the window, the user can edit typein before 
the reading function sees it. See the section "Input From Windows", page 132. 

An activity is a group of windows that the user regards as a single unit. Typically 
an activity consists of a top-level window — one that is a direct inferior of a screen 
— and all its direct and indirect inferior windows. An example of an activity is a 
top-level Lisp Listener. Sometimes an activity consists of a non-top-level window and 
all its direct and indirect inferior windows. One example is a Lisp Listener inside a 
Split Screen frame. 

The concept of activity is only partially implemented in the window system. No 
separate object represents an activity. Instead, an activity is designated by a 
representative window from that activity. In the usual case, where the windows in 
an activity form a tree, the root of the tree serves as the representative. 

The system contains several generic tools for selecting among activities: These 
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include the SELECT key, FUNCTION s, and the [Select] menu in the System Menu. 
The selected activity is the activity that contains the selected window. When you 
change the selected activity, you also change the selected window. 

You usually select an activity by selecting the representative window of the activity. 
But this window might or might not be selectable itself; sometimes only its inferiors, 
or only some of its inferiors, can become the selected window. When you select an 
activity, the representative window of the activity usually decides which window 
within the activity should become the selected window. 

We say that this window — the one that is to become the selected window when 
the activity is selected — is selected relative to its activity. When you select a 
window relative to its activity, you do not change the selected activity. If an activity 
happens to be the selected activity, then selecting a window relative to that activity 
also makes that window the new selected window. If an activity is not the selected 
activity, then selecting a window relative to that activity changes neither the selected 
activity nor the selected window. 

Whenever you select a window that is part of an activity, that window is selected 
relative to its activity, and that activity becomes the selected activity. 

11.11.2 Frames and Panes 

A frame is a window that is designed to contain other windows inside it. A direct 
inferior window of a frame is called a pane. Many activities consist of a frame and 
its direct and indirect inferior windows. The frame is the representative window of 
this kind of activity. 

A window that is a direct or indirect inferior of a frame can be the selected-pane of 
the frame. The selected-pane is the window that is selected relative to the frame. 
A frame usually cannot become the selected window. Instead, when you select a 
frame, its selected-pane becomes the selected window, unless the selected-pane is 
itself a frame. In that case the selected-pane of the selected-pane becomes the 
selected window. 

You can change the selected-pane of a frame without selecting the activity that the 
frame represents. The next time that activity is selected, the new selected-pane 
becomes the selected window. If that activity happens to be the selected activity, 
then changing the selected-pane of the frame causes the new selected-pane to 
become the selected window. 

If you select a window that is a pane of a frame, that window becomes the selected- 
pane of the frame, and the activity that the frame represents becomes the selected 
activity. 

For more about panes and frames, including constraint frames: See the section 
"Frames", page 175. 
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11.11.3 Messages About Window Selection 

:alias-for-selected-windows Message 

When the :alias-for-selected-windows message is sent to a window, it 
returns the representative window of the receiver's activity. If two windows 
have the same alias-for-selected-windows, they belong to the same activity. 

This message is sent by both the system and the user and may be received 
by either, although usually the system-supplied methods suffice. The default 
method (of tv:sheet) returns the window to which the message is sent, 
declaring the window to be in an activity by itself. tv:select-relative-mixin 
supplies a method that returns the superior's alias, unless the window to 
which the message is sent is a top-level window (that is, its superior is a 
screen); in that case it returns the window itself. tv:pane-mixin and 
tv:basic-typeout-window supply methods that return the superior's alias. 

:name-for-selection Message 

The :name-for-selection message to a window returns nil if the window is 
not supposed to be selected. Otherwise, it returns a string that serves as the 
name of the window in menus of selectable windows. 

This message is sent by many parts of the user interface. Some use it just 
as a predicate; others put the returned string into a menu. 

This message is usually received by the user. The default method (of 
tvrsheet) returns nil. tv:select-mixin provides a method that computes a 
name based on the window's label, if it has one, or else on the window's 
name. Many application programs shadow this method and supply their own. 

rselectable-windows Message 

The rselectable-windows message to a window returns a menu item-list of 
activities containing or inferior to the window. The :name-for-selection and 
:alias-for-selected-windows messages are used to discover the available 
activities. When sent to a screen, this message returns a menu item-list of 
all the activities that screen contains. 

This message is sent by [Select] in the System Menu and is received by the 
system. Users shouldn't need to send this message or to define methods for 
it. 

:select-relative Message 

The rselect-relative message to a selectable window selects the window 
relative to its activity, but doesn't select a different activity. 

t* i.i :„ j i.i j. ; j.i_r_ 1 i a_ ii j.; 11 j.i 

xx iixxc Yvmuuyy tuai> iclciyco i/xxio mcooagc uciuiigo v\j tuc ocuxxo tx^viy ivj ass 111c 

currently selected window, the receiver becomes the new selected window. 
Otherwise, the window that receives this message sends the :inferior-select 
message to its superior to select the receiver relative to its activity. 
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User programs should send the rselect-relative message rather than :select 
or :mouse-select, unless they are really responding to a user command to 
switch activities. Using rselect-relative rather than reelect to change 
windows within an activity ensures that the right thing happens when that 
activity is not the selected one and avoids suddenly changing the selected 
activity without the consent of the user. 

This message returns no significant values. It is sent by the user and 
received by the system. Users should not need to define methods for it. 

:inferior-select sheet Message 

The :inferior-select message to a window returns non-nil if it is okay to 
select sheet, or nil if it is not okay. If the message returns nil, presumably 
some appropriate action such as selecting a different window has already been 
performed. 

This message is sent and received by the system. It is normally sent under 
two circumstances: 

• If a window is selected, and if the window includes a flavor that makes 
it participate in its superior's activity, the window sends its superior an 
dnferior-select message with itself as the argument. Flavors that 
make windows participate in their superiors' activities include 
tv:select-relative-murin, tv:pane-mixin, and 
tv:basic-typeout- window. 

• If a window receives a tselect-relative message and the window's 
activity is not the currently selected activity, it sends its superior an 
:inferior-select message with itself as the argument. 

The dnferior-select message is propagated upwards through all levels of the 
window hierarchy until it reaches a screen. This informs the direct and 
indirect superiors of window that it has been selected (or selected relative to 
its activity). When a frame receives an :inferior-select message, it saves 
sheet as its selected-pane and passes the message on, substituting itself for 
sheet. 

All currently extant methods return a non-nil value. Only panes look at the 
returned value; they don't allow themselves to be selected if the returned 
value is nil. This permits a frame to refuse to allow its selected-pane to be 
changed. 

:select-pane pane Message 

The :select-pane message to a frame makes pane the selected-pane of the 
frame, pane must be either an exposed inferior of the frame or nil, which 
means to set the selected-pane to nil. This message also deselects the 
current selected-pane if it is a window different from pane. Unless pane is 
nil, this message sends pane a :select-relative message. 
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:selected-pane Message 

The :selected-pane message to a frame returns the selected-pane of the 
frame. This message is sent by users and received by the system. 

:selected-pane pane (for tvrbasic-constraint-frame) Init Option 

Makes pane the selected-pane of this frame, pane can be the symbol used in 
the rpanes init option to name the pane. 

rmouse-select &optional (save-selected t) Message 

The :mouse-select message to a window selects the window as a result of a 
user command, usually clicking the mouse on it. This takes care of various 
window system issues, such as making sure that typeahead goes to the 
correct activity and getting rid of any temporary windows that are covering 
this window, preventing it from being exposed. 

The operation fails and returns nil if this window is not contained inside its 
superior (it might be too large), which prevents it from being exposed. The 
operation can also fail and return nil if the message is sent to a frame whose 
selected-pane is nil. If the operation succeeds, the message returns t. 

If save-selected is not nil, the previously selected activity is saved for restoring 
by the function s command and the :deselect message. 

The rmouse-select message to a pane (a window with tv:pane-mixin) 
selects the activity of which the pane is a part, without changing its selected- 
pane. Thus, the message does not necessarily select the window to which it 
is sent; it might select some other window in the same activity. 
:mouse-select is intended to be a command for switching activities. 

User programs should send the rselect-relative message rather than reelect 
or rmouse-select, unless they are really responding to a user command to 
switch activities. Using rselect-relative rather than rmouse-select or 
rselect to change windows within an activity ensures that the right thing 
happens when that activity is not the selected one and avoids suddenly 
changing the selected activity without the consent of the user. 

This message is sent by many parts of the user interface. 

This message is usually received by the system, although users could define 
methods for it: either a method that returns nil to prevent a window from 
being selected, or a daemon. The default method is denned on 
tvressential-window. 

rselect &optional (save-selected t) Message 

The rselect message is sent to a selectable window by a user program or by 
a part of the user interface to change the selected activity. It is also sent by 
the system to notify a window when it becomes the selected window, either 
because of a change of activities or because of selection of this window instead 
of a different window within the same activity. 
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This message is received by the system and is also received by user daemons 
that wish to be notified when a window becomes selected. 

If save-selected is not nil, the previously selected activity is saved for restoring 
by the FUNCTION s command and the rdeselect message. 

The message returns t if it works, nil if it fails. It can fail when sent to a 
pane if the :inferior-select message that the pane sends to the frame 
returns nil. It can also fail when sent to a frame that has no selected-pane. 

User programs should send the rselect-relative message rather than rselect 
or rmouse-select, unless they are really responding to a user command to 
switch activities. Using rselect-relative rather than rselect to change 
windows within an activity ensures that the right thing happens when that 
activity is not the selected one and avoids suddenly changing the selected 
activity without the consent of the user. 

rdeselect &optional (restore-selected t) Message 

The rdeselect message is sent to a selectable window by a user program or 
by a part of the user interface to change the selected activity. It is also sent 
by the system to notify a window when it ceases to be the selected window, 
either because of a change of activities or because of selection of a different 
window within the same activity. When sent by the system as a notification 
of deselection, restore-selected is always nil. 

This message is received by the system and is also received by user daemons 
that wish to be notified when a window becomes deselected. Note that this 
message can be sent to a window that is not the selected window; in that 
case it is supposed to do nothing. 

If :deselect is sent to the selected window and restore-selected is not nil, the 
previously selected activity is selected. 

11.11.4 Flavors Related to Window Selection 

tv:select-mixin Flavor 

This flavor allows a window to be selectable. It provides methods for the 
rselect, rdeselect, rselect-relative, and :name-for-selection messages. 

tv:select-relative-mixin Flavor 

This flavor makes a window participate in the same activity as its superior. 
It provides a method for the :alias-for-selected-windows message that 
returns the window if its superior is a screen, or the superior's alias 
otherwise. It also provides a daemon for the :select message that sends an 
rinferior-select message to the superior with an argument of the window. 

This flavor does not provide a method for the rselect-relative message; that 
is handled by tvrselect-mixin. 
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tv:dont-select-with-mouse-mixin Flavor 

This flavor provides a :name-for-selection message that returns nil, so that 
the user interface does not treat the window as a candidate for selection. 

tv:basic-frame Flavor 

This flavor provides methods that allow the frame to serve as the 
representative window of its activity. Usually a frame cannot become the 
selected window, but this flavor provides methods that handle messages about 
selection, typically by operating on the selected-pane instead of the frame. 
The rselect, rdeselect, and tselect-relative methods just pass these 
messages on to the selected-pane when one exists; otherwise they return nil. 

This flavor provides a handler for the :select-pane message that decides 
which pane should be selected when the activity is selected. The 
:inferior-select method saves the argument as the selected-pane and sends 
the message on to the frame's superior with the frame as argument. The 
:name-for-selection method returns the name-for-selection of the selected- 
pane if a selected-pane exists and has a name-for-selection; otherwise, the 
method returns the name of the frame. 

tv:pane-mixin Flavor 

The flavor of any window used as a pane of a frame must have 
tv:pane-mhrin as one of its components. For example, the flavor 
tv:window-pane, used when you want a pane of a frame that understands 
everything that tv:window does, is defined as follows: 

(defflavor tv: window- pane () (tv:pane-mixin tv:window)) 

Among other things, tv:pane-mixin provides methods that let the pane 
participate in its superior's activity. The :alias-for-selected-windows 
method returns the superior's alias. When a window of this flavor receives a 
rselect message, it first sends its superior an :inferior-select message. If 
the :inferior-select message returns nil, the rselect message fails and just 
returns nil. When a window of this flavor receives a :mouse-select 
message, it passes the message on to its superior. 

tv:pane-no-mouse-select-mixin Flavor 

A mixin flavor to make a window a pane of a frame and ensure that it 
cannot be selected from a system menu. This flavor includes tv:pane-mixin 
and tv:dont-select-with-mouse-mixiiL 

11.11.5 Selecting a Window Temporarily 

ivrwindow-caii-reiative {.window &opuonai final-action &rest Special Form 

final-action-args) &body body 
Temporarily selects a window relative to its activity, executes the body, then 
(in an unwind-protect) restores the previous selected-pane of that activity. 
This uses the :select-relative message. 
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window is a variable that is bound to the window to be selected. If 
final-action is specified, it is a message to be sent to window when done with 
it, and final-action-args are forms supplying arguments to that message. 
final-action is often :deactivate. 

tv:window-call-relative is preferred over tv:window-call for use by 
application programs that are not responding to an explicit user command to 
switch activities. 

tv:window-call (window &optional final-action &rest Special Form 

final-action-args) &body body 
Temporarily selects a window — selecting a new activity if the window is not 
part of the currently selected activity — executes the body, then (in an 
unwind-protect) usually restores the previously selected activity. The 
previously selected activity is not restored if at that time the selected window 
is not window or a direct or indirect inferior of it. This heuristic deals with 
the case where the user has switched activities explicitly during the execution 
of body. 

This uses the rselect message but is different from using the save-selected 
and restore-selected arguments to rselect and tdeselect: tv:window-call 
restores the activity that was current when its execution began, not the 
second most recently selected activity, as sending a :deselect message with 
an argument of t would. 

window is a variable that is bound to the window to be selected. If 
final-action is specified, it is a message to be sent to window when done with 
it, and final-action-args are forms supplying arguments to that message. 
final-action is often deactivate. 

tv.window-call-relative is preferred over tv:window-call for use by 
application programs that are not responding to an explicit user command to 
switch activities. 

tv:window-mouse-call (window &optional final-action &rest Special Form 

final-action-args) &body body 
This is similar to tv:window-call but uses rmouse-select instead of rselect 
to select window. It is used by parts of the user interface that want the 
temporary-window-clearing features of :mouse-select. 



702 

Programming the User Interface March 1985 



703 
March 1985 Using the Window System 



12. Window Flavors and Messages 



12.1 Overview of Window Flavors and Messages 

In this section we present the actual messages that can be sent to windows to 
examine and alter their state and to get them to do things. Just how a window 
reacts to a message depends on what flavor it is an instance of, and so we will also 
explain the various flavors that exist. This section also explains how to create new 
windows, and how to compose new flavors of windows by mixing together existing 
flavors. 

Windows have a wide variety of functions, and can respond to any of a large set of 
messages. To help you find your way around among all the messages, this chapter 
groups together messages that deal with the same facet of the functionality of 
windows. Here is a summary of the various groups of messages that are 
documented. 

First of all, a window can be used as if it were the screen of a display computer 
terminal. You can output characters at a cursor position, move the cursor around, 
selectively clear parts of the window, insert and delete lines and characters, and so 
on, by sending stream messages to the window. This way, windows can act as 
output streams, and any function that takes a stream for its argument (such as 
print or format) can be passed a window. Characters can be drawn in any of a 
large set of fonts (typefaces), and you can switch from one to another within a single 
window. Windows do useful things when you try to run the cursor off the right or 
bottom edges; they also have a facility called more processing to stop characters from 
coming out faster than you can read them. 

In addition to characters from fonts, you can also display graphics (pictures) on 
windows. There are functions to draw lines, circles, triangles, rectangles, arbitrary 
polygons, circle sectors, and cubic splines. 

A window can also be used for reading in characters from the keyboard; you do this 
by sending it stream input messages (such as :tyi and rlisten). This way, windows 
can act as input streams, and any function that takes a stream for its argument 
(such as read or readline) can be passed a window. Each window has an I/O 
buffer holding characters that have been typed at the window but not read yet, and 
there are messages that deal with these buffered characters. You can force keyboard 
input into a window's I/O buffer; frequently two processes communicate by one 
process's forcing keyboard input into an I/O buffer which another process is reading 
characters from. 

Each window can have any number of blinkers. The kind of blinker that you see 
most often is a blinking rectangle the same size as the characters you are typing; 
this blinker shows you the cursor position of the window. In fact, a window can 
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have any number of blinkers; they need not follow the cursor (some do and some 
don't) and they need not actually blink (some do and some don't). For example, the 
editor shows you what character the mouse is pointing at; this blinker looks like a 
hollow rectangle. The arrow that follows the mouse is a blinker, too. Blinkers are 
used to add visible ornaments to a window; a blinker is visible to the user, but while 
programs are examining and altering the contents of a window the blinkers all go 
away. This means that blinkers do not affect the contents of the window as seen 
from programs; whenever a program looks at a window, the blinkers are all turned 
off. The reason for this is so that you can draw characters and graphics on the 
window without having to worry whether the flashing blinker will overwrite them. 
If you have anything that should appear to the user but not be visible to the 
program, then it should be a blinker. The window system provides a few kinds of 
blinkers, and you can define your own kinds. Blinkers are instances of flavors, too, 
and have their own set of messages that they understand. 

Any program can use the mouse as an input device. The window system provides 
many ways for you to get at the mouse. Some of them are very easy to use, but 
don't have all the power you might want; others are somewhat more difficult to use 
but give you a great deal of control. The window system also takes responsibility for 
figuring out which of many programs have control over the mouse at any time. 

There are a large number of messages for manipulating the size and position of a 
window. You can specify these numerically, ask for the user to tell you (using the 
mouse), ask for a window to be near some point or some other window, and so on. 

A window's area of the screen is divided into two parts. Around the edges of the 
window are the four margins; while the margins can have zero size, usually there is 
a margin on each edge of the window, holding a border and sometimes other things, 
such as a label. The rest of the window is called the inside; regular character 
drawing and graphics drawing all occur on the inside part of the window. You have 
a great deal of control over what goes in the margins of a window. Control can be 
exercised either by mixing in different flavors that put different things in the 
margins or by specifying parameters such as the width of the borders or the text to 
appear in the label. 

You can create windows with several panes (inferior windows). These are called 
frames, and there are messages that deal specifically with frames, their configuration, 
and their inferiors. 

Sometimes a background process wants to tell the user something, but it does not 
have any window on which to display the information, and it does not want to pop 
one up just for one little message. A facility is provided wherein the process can 
send such notification messages to the selected window, and it will find some way to 
get the message to the user. Different windows do different things when someone 
tries to use them for notification. 

Screens are windows themselves; they also have extra functions that windows don't 
have, since they do not have superiors and since they correspond to actual pieces of 
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display hardware. Screens can be either black-and-white or color. Color screens 
have more than one bit for each pixel, and most operations on windows do 
something reasonable on color screens. But the extra bits give you extra flexibility, 
and so there are some more powerful things you can do to manipulate colors. Color 
screens also have a color map, that specifies which values of the pixels display which 
colors. 

There are also messages for changing the status of windows: whether they are 
active, exposed, or selected. There are several options to exactly how exposure and 
deexposure should affect the screen. You can also ask windows to refresh their 
contents, kill them, and so on. There are also ways to deal with the screen 
manager, including messages to examine and alter priorities, and other functions and 
variables and flavors for affecting what the screen manager does. 

You can define your own fonts, and/or convert fonts from other formats to the Lisp 
Machine's format. Font characters have various attributes such as their height, 
baseline, left kern, and so on. 

The status line at the bottom of the screen shows the user something about the 
state of the Lisp Machine. There are several functions for controlling just what it 
does and for getting things to be displayed in it. 

The window system provides a facility called I/O buffers. An I/O buffer is a general 
purpose first-in first-out ring buffer, with various useful features. Programs can use 
I/O buffers for anything else, too; it need not even have anything to do with the 
window system. 

There are some interrelationships between windows and processes. Exactly how 
processes and windows relate depends on the flavor of the window, and, as usual, 
there are several messages to manipulate the connections. 



12.2 Getting a Window to Use 

12.2.1 Flavors of Basic Windows 

Many programs never need to create any new windows. Often, all you are 
interested in doing is sending messages to standard-output and standard-input 
and performing the extended stream operations offered by windows to read and type 
characters, position the cursor (and other things that you do on display terminals), 
and draw graphics. Other programs want to create their own windows for various 
reasons; a common way to organize an interactive system on the Lisp Machine is to 
create a process that runs the command loop of the system, and have it use its own 
window or suite of windows to communicate with the user. This kind of system is 
what the editor and Zmail use, and it is very convenient to deal with. 

Whichever of these you use, it is important for you to know what flavor of window 
you are getting. Some flavors accept certain messages that are not handled by 



106 

Programming the User Interface March 1985 



others. The details of different flavors' responses to the same message may vary in 
accordance with what those flavors are supposed to be for. The following is a 
discussion of window flavors. 

The most primitive flavor of window is called tvrminimum-window; it is the basic 
flavor on which all other window flavors are built, and it contains the absolute 
minimum amount of functionality that a window must have to work. 
tv:minimum-window itself is built on a number of other flavors that provide the 
"essential" attributes of windows. For reference, tv:minimum-window is defined as 
follows (ignoring defflavor options): 

(defflavor tv: mini mum-window () 
(tv: essential -expose tv: essential -activate 
tv: essential -set-edges tv: essential -mouse 
tvressential-window)) 

tv:essential-window, in turn, is built on the base flavor for all windows, tv:sheet. 

There is another flavor called tv:window, which is built on tv:minimum-window 
and has about six mixins that do a variety of useful things. When you cold boot a 
Lisp Machine, the window you are talking to is of flavor tvrlisp-listener, which is 
built on tvrwindow and has three more mixins. tv:window has what you need to 
do the normal things that are done with windows; tv:minimum-window is missing 
messages for character output and input, selection, borders, labels, and graphics, and 
so there isn't much you can do with it. Anything built on tv:window, including 
Lisp Listeners, will be able to accept all the basic messages. 

Some programs may benefit from more carefully tailored mixings of flavors. For the 
benefit of programmers who want to do this, we specify below, with each message 
and init option, which flavor actually handles it. If you are just using tv:window 
then you don't really care exactly what mixin specific features are in; you just need 
to know which ones are in tv:window. With the discussion of each flavor or group 
of messages, we will say which relevant flavors are in tvrwindow and which are 
not. For reference, tvrwindow is defined (ignoring defflavor options) as follows: 

(defflavor tvrwindow () 
(tv:stream-mixin tv:borders-mixin tvrlabel-mixin 
tv:select-mixin tv:graphics-mixin tv:minimum-window)) 

So if you use tvrwindow then you have all the above mixins, and can take 
advantage of their features. 

12.2.2 Creating a Window 

If you want to create your own window, you use the tvrmake-window function. 
Never try to instantiate a window flavor yourself with make-instance or 
instantiate-flavor; always use tvrmake-window which takes care of a number of 
internal system issues. 
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tv:make-window flavor-name &rest init-options Function 

Create, initialize, and return a new window of the specified flavor. The 
init-options argument is the init-plist (it is just like the &rest argument of 
make-instance). The allowed initialization options depend on what flavor of 
window you are making. Each window flavor handles some init options; the 
options and what they mean are documented with the documentation of the 
flavor. 

Example: 

( tv : make-wi ndow * tv : 1 i sp- 1 i s tener 
'.•borders 4 

* : font-map (list fonts rbigfnt) 
' :vsp 6 

':edges-from ':mouse 
' :expose-p t) 

creates an exposed Lisp Listener with big characters and lots of vertical space 
between lines. 

:init init-plist of tvrsheet Method 

Sets initial characteristics of the window, processing options in init-plist. 
This message is sent by the system; you might need to supply an rafter 
daemon for it. 

rsuperior superior (for tvtsheet) Init Option 

Makes superior the superior window of the window being created. 

:activate-p t-or-nil (for tvressential-window) Init Option 

If this option is specified non-nil, the window is activated after it is created. 
The default is to leave it deactivated. 

:expose-p t-or-nil (for tv:essential-window) Init Option 

If this option is specified non-nil, the window is exposed after it is created. 
The default is to leave it deexposed. If the value of the option is not t, it is 
used as the first argument to the :expose message (the turn-on-blinkers 
option). 

defwindow-resource name parameters &rest options Special Form 

Defines a resource of windows, name is the name of the resource. 
parameters is a lambda-list of parameters to defresource. options are 
alternating keywords and values: 

Keyword Value 

rinitial-copies Number of windows to be created during evaluation of 

defresource form. Default: 1. 

rsuperior A form to be evaluated when the resource is allocated 
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:make- window 



:constructor 



:reusable-when 



to return the superior window of the desired window. 
If this is not supplied, the superior is the value of 
tv:mouse-sheet. 

List of flavor name and options to tv:make-window, 
which will be called to make new windows. One of the 
options can be rsuperior. 

A form or the name of a function to make new 
windows. You must supply either :make-window or 
constructor. 

Either :deexposed or :deactivated. Specifies when a 
window can be reused. Supply this when you use 
allocate-resource instead of using-resource to 

allocate resources. Default: reusable when not locked 
and not in use. 



12.3 Character Output to Windows 



12.3.1 How Windows Display Characters 

A window can be used as if it were the screen of a display computer terminal, and it 
can act as an output stream. The flavor tvrsheet implements the messages of the 
Lisp Machine output stream protocol. It implements a large number of optional 
messages of that protocol, such as :insert-line. The tv:sheet flavor is a component 
of all windows. Every window has a current cursor position; its main use is to say 
where to put characters that are drawn. The way a window handles the messages 
asking it to type out is by drawing that character at the cursor position, and moving 
the cursor position forward past the just-drawn character. 

In the messages below, the cursor position is always expressed in "inside" 
coordinates; that is, its coordinates are always relative to the top-left corner of the 
inside part of the window, and so the margins don't count in cursor positioning. 
The cursor position always stays in the inside portion of the window-never in the 
margins. The point (0,0) is at the top-left corner of the window; increasing x 
coordinates are further to the right and increasing y coordinates are further towards 
the bottom. (Note that y increases in the down direction, not the up direction!) 

To draw a character "at" the cursor position basically means that the top-left corner 
of the character will appear at the cursor position; so if the cursor position is at 
position (0,0) and you draw a character, it will appear at the top-left corner of the 
window. (Things can actually get more complicated when fonts with left-kerns are 
used.) 

When a character is drawn, it is combined with the existing contents of the pixels of 
the window according to an alu function. For a description of the different alu 
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functions: See the section "Graphic Output to Windows", page 118. When 
characters are drawn, the value of the window's char-aluf is the alu function used. 
Normally, the char-aluf says that the bits of the character should be bit-wise logically 
ored with the existing contents of the window. This means that if you type a 
character, then set the cursor position back to where it was and type out a second 
character, the two characters will both appear, ored together one on top of the 
other. This is called overstriking. 

Every window has a font map. A font map is an array of fonts in which characters 
on the window can be typed. At any time, one of these is the window's current 
font; the messages that type out characters always type in the current font. Details 
of fonts and the font map are gone into later in detail: See the section "Fonts: 
Flavors and Messages". For now, it is only important to understand fonts in order 
to understand what the character-width and line-height of the window are; these 
two units are used by many of the messages documented in this section. The 
character-width is the char-width attribute-the width of a "typical" character-of the 
first font in the font map. The line-height is the sum of the vsp of the window and 
the maximum of the char-heights of all the fonts. The vsp is an attribute of the 
window that controls how much vertical spacing there is between successive lines of 
text. That is, each line is as tall as the tallest font is, and also you can add vertical 
spacing between lines by controlling the vsp of the window. 

Every window has a current font, which the messages use to figure out what font to 
type in. If you are not interested in fonts, you can ignore this and something 
reasonable will happen. In some fonts, all characters have the same width; these 
are called fixed-width fonts, the default font is an example. In other fonts, each 
character has its own width; these are called variable-width fonts. In a variable- 
width font, expressing horizontal positions in numbers of characters is not 
meaningful, since different characters have different widths. Some of the functions 
below do use numbers of characters to designate widths; there are warnings along 
with each such use explaining that the results may not be meaningful if the current 
font has variable width. 

Typing out a character does more than just drawing the character on the screen. 
The cursor position is moved to the right place; nonprinting characters are dealt 
with reasonably; if there is an attempt to move off the right or bottom edges of the 
screen, the typeout wraps around appropriately; more breaks are caused at the right 
time if more processing is enabled. Here is the complete explanation of what typing 
out a character does. You may want to remind yourself how the Lisp Machine 
character set works. See the section "The Character Set" in Reference Guide to 
Streams, Files, and I/O. You don't have to worry much about the details here, but 
in case you ever need to know, here they are. If you aren't interested, skip ahead 
to the definitions of the messages. 

First of all, as was explained earlier, before doing any typeout the process must wait 
until it has the ability to output. See the section "Window Exposure and Output", 
page 82. The output hold flag must be off and the window must not be temp- 
locked. 
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Before actually typing anything, various exceptional conditions are checked for. If an 
exceptional condition is discovered, a message is sent to the window; the message 
keyword is the name of the condition. Different flavors handle the various 
exceptions different ways; you can control how exceptions are handled by what 
flavors your window is made of. First, if the y-position of the cursor is less than one 
line-height above the inside bottom edge of the window, an :end-of-page-exception 
happens. The handler for this exception in the tv:sheet flavor moves the cursor 
position to the upper-left-hand corner of the window and erases the first line, doing 
the equivalent of a :clear-rest-of-line operation. 

Next, if the window's more flag is set, a :more-exception happens. The more flag 
gets set when the cursor is moved to a new line (for example, when a #\return is 
typed) and the cursor position is thus made to be below the more vpos of the 
window. (If tvrmore-processing-global-enable is nil, this exception is suppressed 
and the more flag is turned off.) The :more-exception handler in the tv:sheet 
flavor does a :clear-rest-of-line operation, types out **MORE**, waits for any 
character to be typed, restores the cursor position to where it originally was when 
the :more-exception was detected, does another :clear-rest-of-line to wipe out the 
**MORE**, and resets the more vpos. The character read in is ignored. 

Note that the more flag is only set when the cursor moves to the next line, because 
a #\return is typed, after a :line-out, or by the :end-of-line~exception handler 
described below. It is not set when the cursor position of the window is explicitly 
set (for example, with :set-cursorpos); in fact, explicitly setting the cursor position 
clears the more flag. The idea is that when typeout is being streamed out 
sequentially to the window, :more-exceptions happen at the right times to give the 
user a pause in which to read the text that is being typed, but when cursor 
positioning is being used the system cannot guess what order the user is reading 
things in and when (if ever) is the right time to stop. In this case it is up to the 
application program to provide any necessary pauses. 

The algorithm for setting the more vpos is too complicated to go into here in all its 
detail, and you don't need to know exactly how it works, anyway. It is careful 
never to overwrite something before you have had a chance to read it, and it tries to 
do a **MORE** only if a lot of output is happening. But if output starts happening 
near the bottom of the window, there is no way to tell whether it will just be a 
little output or a lot of output. If there's just a little, you would not want to be 
bothered by a **MORE**. So it doesn't do one immediately. This may make it 
necessary to cause a **MORE** break somewhere other than at the bottom of the 
window. But as more output happens, the position of successive **MORE**s is 
migrated and eventually it ends up at the bottom. 

Finally, if there is not enough room left in the line for the character to be typed 
out, an :end-of-line-exception happens. The handler for this exception in the 
tv:sheet flavor advances the cursor to the next line just as typing a #\return 
character does normally. This may, in turn, cause an :end-of-page-exception or a 
:more-exception to happen. Furthermore, if the right margin character flag is on, 
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then before going to the next line, an exclamation point in font zero is typed at the 
cursor position. When this flag is on, :end-of-line-exceptions are caused a little bit 
earlier, to make room for the exclamation point. 

The way the cursor position goes to the next line when it reaches the right edge of 
the window is called horizontal wraparound. You can make windows that truncate 
lines instead of wrapping them around by using tv:truncating-lines-mixin. 

After checking for all these exceptions, the character finally gets typed out. If it is a 
printing character, it is typed in the current font at the cursor position, and the 
cursor position is moved to the right by the width of the character. If it is one of 
the format effectors #\return, #\tab, and #\backspace, it is handled in a special 
way to be described in a moment. All other special characters have their names 
typed out in tiny letters surrounded by a lozenge, and the cursor position is moved 
right by the width of the lozenge. If an undefined character code is typed out, it is 
treated like a special character; its code number is displayed in a lozenge. 

#\tab moves the cursor position to the right to the next tab stop, moving at least 
one character-width. Tab stops are equally spaced across the window. The distance 
between tab stops is tab-nchars times the character-width of the window, tab-nchars 
defaults to 8 but can be changed. 

Normally #\return moves the cursor position to the inside left edge of the window 
and down by one line-height, and clears the line. It also deals with more processing 
and the end-of-page condition as described above. However, if the window's 
cr-not-newline-flag is on, the #\return character is not regarded as a format 
effector and is displayed as "return" in a lozenge, like other special characters. 

If the character being typed out is a #\backspace, the result depends on the value 
of the window's backspace-not-overprinting-flag. If the flag is 0, as is the default, 
the cursor position is moved left by one character-width (or to the inside left edge, 
whichever is closer). If the flag is 1, #\backspaces are treated like all other special 
characters. 

12.3.2 Messages to Display Characters on Windows 

:tyo ch of tvrsheet Method 

Type ch on the window, as described above. Basically, type the character ch 
in the current font at the cursor position, and advance the cursor position. 

:string-out string &optional (start 0) (end nil) of tvrsheet Method 

Type string on the window, starting at the character start and ending with 
the character end. If end is nil, continue to the end of the string; if neither 
optional argument is given, the entire string is typed. This behaves exactly 
as if each character in the string (or the specified substring) were sent to the 
window with a :tyo message, but it is much faster. 
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:line-out string &optional (start 0) (end nil) of tv:sheet Method 

Do the same thing as :string-out, and then advance to the next line (like 
typing a #\return character). The main reason that this message exists is 
so that the stream-copy-until-eof function can, under some conditions, 
move whole lines from one stream to another; this is more efficient than 
moving characters singly. The behavior of this operation is not affected by 
the :cr-not-newline-flag init option. 

:fresh-line of tvisheet Method 

Get the cursor position to the beginning of a blank line. Do this in one of 
two ways. If the cursor is already at the beginning of a line (that is, at the 
inside left edge of the window), clear the line to make sure it is blank and 
leave the cursor where it was. Otherwise, advance the cursor to the next 
line and clear the line just as if a #\return had been output. The behavior 
of this operation is not affected by the :cr-not-newline-flag init option. 

:insert-char &optional (n V (unit 'zcharacterj of tvrsheet Method 

Open up a space the width of n units in the current line at the current 
cursor position. Shift the characters to the right of the cursor further to the 
right to make room. Characters pushed past the right-hand edge of the 
window are lost. If unit is :character, n is interpreted as the number of 
character-widths to insert; if unit is :pixel, n is interpreted as the number of 
pixels to insert. 

rinsert-string string &optional (start 0) (end nil) (type-too t) of Method 

tv:sheet 

Insert a string at the current cursor position, moving the rest of the line to 
the right to make room for it. 

The string to insert is specified by string; a substring thereof may be 
specified with start and end y as with :string-out. 

string may also be a number, in which case the character with that code is 
inserted. 

If type-too is specified as nil, suppress the actual display of the string, and 
the space that was opened is left blank. 

:insert-line &optional (n V (unit 'tcharacterj of tvrsheet Method 

Take the line containing the cursor and all the lines below it, and move 
them down by n units. The line containing the cursor is moved in its 
entirety, not broken, no matter where the cursor is on the line. A blank line 
is created at the cursor. Lines pushed off the bottom of the window are lost. 
If unit is character, n is interpreted as the number of lines to insert; if 
unit is :pixel, n is interpreted as the number of pixels to insert. 
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12.3.3 Messages to Read or Set Cursor Position 

:read-cursorpos &optional (units 'rpixeD of tvrsheet Method 

Return two values: the x and y coordinates of the cursor position. These 
coordinates are in pixels by default, but if units is rcharacter, the 
coordinates are given in character-widths and line-heights. (Note that 
character-widths don't mean much when you are using variable-width fonts.) 

:set-cursorpos x y &optional (units 'rpixeD of tv:sheet Method 

Move the cursor position to the specified coordinates. The units may be 
specified as with :read-cursorpos. If the coordinates are outside the 
window, move the cursor position to the nearest place to the specified 
coordinates that is in the window. 

:home-cursor of tv:sheet Method 

Move the cursor to the upper left corner of the window. 

:home-down of tv:sheet Method 

Move the cursor to the lower left corner of the window. 

12.3.4 Messages to Remove Characters From Windows 

rrefresh &optional type of tvrsheet Method 

Redisplays the window. Depending on type and the existence of a bit-save 
array, clears the window or restores the image from the bit-save array. This 
message is usually sent by the system. You might need to provide an rafter 
daemon to reconstruct the contents of the window. 

:clear-char &optional char of tvrsheet Method 

Erase the character at the current cursor position. When using variable- 
width fonts, you tell it the character code of the character you are erasing, so 
that it will know how wide the character is (it assumes the character is in 
the current font). If you don't pass the char argument, it simply erases a 
character-width, which is fine for fixed-width fonts. 

:clear-rest-of-line of tvrsheet Method 

Erase from the current cursor position to the end of the current line; that is, 
erase a rectangle horizontally from the cursor position to the inside right edge 
of the window, and vertically from the cursor position to one line-height 
below the cursor position. 

:clear-rest-of-window of tvrsheet Method 

Erase from the current cursor position to the bottom of the window. In 
more detail, first do a rclear-rest-of-line, and then clear all of the window 
past the current line. 
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tclear-window of tvtsheet Method 

Erase the whole window and move the cursor position to the upper left 
corner of the window. 

:delete-char &optional (n 1) (unit 'tcharacter,) of tv:sheet Method 

Without an argument, delete the character at the current cursor position. 
Otherwise, delete n units, starting at the current cursor position. Move the 
display of the part of the current line that is to the right of the deleted 
section leftwards to close the resultant gap. If unit is tcharacter, n is 
interpreted as the number of characters to delete; if unit is rpixel, n is 
interpreted as the number of pixels to delete. 

rdelete-string string &optional (start 0) (end nil) oftvrsheet Method 

This is for deleting specific strings in the current font. It is one of the 
things to use when dealing with variable-width fonts. 

If string is a number, it is considered to be a character code. Excise a region 
exactly as wide as that character at the current cursor position, and move 
the display of the part of the current line that is to the right of the excised 
region leftwards to close the gap. 

If string is a string, excise a region exactly as wide as that string, or a 
substring specified by start and end y and close the gap as in the single- 
character case. 

:delete-line &optional (n V (unit 'rcharacterj of tv:sheet Method 

Without an argument, delete the line that the cursor is on. Otherwise delete 
n units, starting with the one the cursor is on. Move up the display below 
the deleted section to close the resulting gap. If unit is character, n is 
interpreted as the number of lines to delete; if unit is :pixel, n is interpreted 
as the number of pixels to delete. 

12.3.5 Messages About Character Width and Cursor Motion 

:character-width char &optional (font current-fontj of tvrsheet Method 

Return the width of the character char y in pixels. The current font is used 
if font is not specified. If char is a backspace, :character-width can return 
a negative number. For tab, the number returned depends on the current 
cursor position. If char is return, the result is defined to be zero. 

rcompute-motion string &optional (start 0) (end nil,) (x Method 

cursor-^) (y cursor-yj (cr-at-end-p nil) 
(stop-x 0) stop-y of tvrsheet 
This is used to figure out where the cursor would end up if you were to 
output string using :string-out. It does the right thing if you give it just 
the string as an argument, start and end can be used to specify a substring 
as with :string-out. x and y can be used to start your imaginary cursor at 
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some point other than the present position of the real cursor. If you specify 
cr-at-end-p as t, it pretends to do a :line-out instead of a :string-out. stop-x 
and stop-y define the size of the imaginary window in which the string is 
being printed; the printing stops if the cursor becomes simultaneously * both 
of them. These default to the lower left-hand corner of the window. 

The method does a triple-value return of the x and y coordinates you ended 
up at and an indication of how far down the string you got. This indication 
is nil if the whole string (or the part specified by start and end) was 
exhausted, or the index of the next character to be processed when the 
stopping point (end of window) was reached, or t if the stopping point was 
reached only because of an extra carriage return due to cr-at-end-p being t. 

All coordinates for this message are in pixels. 

rstring-length string &optional (start 0) (end nil) stop-x (font Method 

current-font,) (start-x 0) of tv:sheet 

This is very much like rcompute-motion, but works in only one dimension. 
It tells you how far the cursor would move if string were to be displayed in 
the current font starting at the left margin, or at start-x if that is specified. 
start and end work as with :string-out to specify a substring of string. If 
stop-x is not specified or nil, the window is assumed to have infinite width; 
otherwise the simulated display will stop when a position stop-x pixels from 
the left edge is reached. The font can be specified. 

rstring-length returns three values: where the imaginary cursor ended up, 
the index of the next character in the string (the length of the string if the 
whole string was processed, or the index of the character which would have 
moved the cursor past stop-x), and the maximum x-coordinate reached by the 
cursor (this is the same as the first value unless there are #\return 
characters in the string). 

12.3.6 Window Attributes for Character Output 

The following messages and initialization options initialize, get, and set various 
window attributes which are relevant to the typing out of characters. For messages 
to manipulate the current font: See the section "Font Messages to Windows", page 
141. 

:more-p t-or-nil (for tv:sheet) Init Option 

Initialize whether the window should have more processing. It defaults to t. 

:more-p of tvrsheet Method 

Return t if more processing is enabled; otherwise, return nil. 
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:set-more-p more-p of tvrsheet Method 

If more-p is nil, turn off more processing; otherwise turn it on. 

tv:autoexposing-more-mixin Flavor 

If you mix in this flavor, when a :more-exception happens, the window will 
be exposed (a :expose message will be sent to it). This is intended to be 
used in conjunction with having a deexposed typeout action of rpermit, so 
that a process can type out on a deexposed window and then have the 
window expose itself when a **MORE** break happens. 

:vsp n-pixels (for tvrsheet) Init Option 

Initialize the window's vsp. It defaults to 2. 

:vsp of tvrsheet Method 

Return the value of vsp for this window. 

:set-vsp new-vsp of tvrsheet Method 

Set the value of vsp for this window to new-vsp. 

:reverse-video-p of tvrsheet Method 

Return nil normally or t if the window displays in white on black rather 
than black on white. This is separate from the whole screen's inverse video 
mode (set by function c). 

:set-reverse-video-p t-or-nil of tvrsheet Method 

Enable or disable reverse-video display. Changing this mode inverts all of the 
bits in the window. 

rdeexposed-typeout-action action (for tv:sheet) Init Option 

Initialize the deexposed typeout action of the window to action. It defaults to 
♦.normal. 

rdeexposed-typeout-action of tv:sheet Method 

Return the deexposed typeout action of the window. 

:set-deexposed-typeout-action action of tvrsheet Method 

Set the deexposed typeout action of the window to action. 

:deexposed-typein-action action (for tvrsheet) Init Option 

Initialize the deexposed typein action of the window to action. It defaults to 
mormal. 

rdeexposed-typein-action of tvrsheet Method 

Return the deexposed typein action of the window. 

:set-deexposed-typein-action action of tvrsheet Method 

Set the deexposed typein action of the window to action. 
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:right-margin-character-flag x (for tvrsheet) Init Option 

If x is 1, print an exclamation point in the right margin when 
:end-of-line-exception happens; if x is 0, don't. It defaults to 0. 

:backspace-not-overprinting-flag x (for tvrsheet) Init Option 

If x is 0, typing #\backspace will move the cursor position backward; if it is 
1, typing #\backspace will display "overstrike" in a lozenge (that is, 
#\backspace will be just like other special characters). It defaults to 0. 

:cr-not-newline-flag x (for tv:sheet) Init Option 

If x is 0, typing #\return will move the cursor position to the beginning of 
the next line and clear that line; if it is 1, typing #\return will display 
"return" in a lozenge (that is, #\return will be just like other special 
characters). It defaults to 0. This flag does not affect the behavior of the 
:line-out nor the :fresh-line messages. 

:tab-nchars n (for tvrsheet) Init Option 

n is the separation of tab stops on this window, in units of the window's 
char-width. This controls how the #\tab character prints, n defaults to 8. 

12.3.7 Line-truncating Windows 

tv:truncatable-lines-mixin Flavor 

If you mix in this flavor and the window's truncate line out flag is on, 
typeout does not wrap around when lines are too long. That is, when the 
cursor is near the right-hand edge of the window and an attempt is made to 
type out a character, the character is not typed out; text is truncated at the 
edge of the window. When the truncate line out flag is turned off, this 
flavor has no effect. 

tv:line-truncating-mixm Flavor 

An obsolete flavor that is the same as tv:truncatable-lines-mixirL The 
name is confusing; when this flavor is mixed in, truncation is enabled only if 
the window's truncate line out flag is on. Otherwise, it has no effect. 
tv:truncatable-lines-mixin is built on this flavor for the sake of two- 
argument typep. 

tv:truncating-lines-mixin Flavor 

When this flavor is mixed in, lines of output that are too long to fit inside 
the window do not wrap around but are truncated at the edge of the 
window. This flavor is built on tv:truncatable-lines-mixiiL It initializes 
the window's truncate line out flag to be on. 

tvrtruncating-window Flavor 

This flavor is built on tv:window with tv:truncating-lines-mixin mixed in. 
If you instantiate a window of this flavor, it will be like regular windows of 
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flavor tv:window except that lines will be truncated instead of wrapping 
around. 

:truncate-line-out of tv:sheet Method 

Returns t if the window's truncate line out flag is set, or nil if it is not. 

:set-truncate-line-out new-value oftv:sheet Method 

Sets the value of the window's truncate line out flag. If new-value is t the 
flag is turned on; if nil, it is turned off. 



12.4 Graphic Output to Windows 

12.4.1 How Windows Display Graphic Output 

A window can be used to draw graphics (pictures). There is a set of messages for 
drawing lines, circles, sectors, polygons, cubic splines, and so on, implemented by the 
flavor tv:graphics-mixin. The tv:graphics-mixin flavor is a component of the 
tv:window flavor, and so the messages documented below will work on windows of 
flavor (or flavors built on) tvrwindow. 

There are also some messages in this section that are in tv:sheet or 
tv:stream-mixin rather than tv:graphics-mixin, because they are likely to be 
useful to any window that can draw characters, but such windows might not want 
the full functionality of tv:graphics-mbrin. These messages are :draw-rectangle, 
and the :bitblt message and its relatives. (If you are building on tvrwindow 
anyway, this doesn't affect you, since tv:window includes both of these flavors.) 

The cursor position is not used by graphics messages; the messages explicitly specify 
all relevant coordinates. All coordinates are in terms of the inside size of the 
window, just like coordinates for typing characters; the margins don't count. 
Remember that the point (0,0) is in the upper left; increasing y coordinates are 
lower on the screen, not higher. Coordinates are always integers. 

As with typing out text, before any graphics are typed the process must wait until it 
has the ability to output. The output hold flag must be off and the window must 
not be temp-locked. The other exception conditions of typing out are not relevant to 
graphics. 

All graphics functions clip to the inside portion of the window. This means that 
when you specify positions for graphic items, they need not be inside the window; 
they can be anywhere. Only the portion of the graphic that is inside the inside part 
of the window will actually be drawn. Any attempt to write outside the inside part 
of the window simply won't happen. 

There are a few simple microcoded primitives for drawing graphics. They can be 
used for drawing pictures into Lisp arrays. However, when drawing on windows you 
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should send the documented messages rather than directly calling the microcode 
primitives because these messages provide several essential services which are too 
complex for the microcode, such as protecting blinkers from being affected from 
drawing, and locking out other processes. 

12.4.2 Alu Functions 

Most of the messages that produce graphic output on windows take an alu 
argument, which controls how the bits of the graphic object being drawn are 
combined with the bits already present in the window. In most cases this argument 
is optional and defaults to the window's char-aluf, the same alu function as is used 
to draw characters, which is normally inclusive-or. The following variables have the 
most useful alu functions as their values: 

tv:alu-ior Variable 

Inclusive-or alu function. Bits in the object being drawn are turned on and 
other bits are left alone. This is the char-aluf of most windows. If you 
draw several things with this alu function, they will write on top of each 
other, just as if you had used a pen on paper. 

tv:alu-andca Variable 

And-with-complement alu function. Bits in the object being drawn are 
turned off and other bits are left alone. This is the erase-aluf of most 
windows. It is useful for erasing areas of the window or for erasing 
particular characters or graphics. 

tv:alu-xor Variable 

Exclusive-or alu function. Bits in the object being drawn are complemented 
and other bits are left alone. Many graphics programs use this. The 
graphics messages take quite a bit of care to do "the right thing" when an 
exclusive-or alu function is used, drawing each point exactly once and 
including or excluding boundary points so that adjacent objects fit together 
nicely. The useful thing about exclusive-or is that if you draw the same 
thing twice with this alu function, the window's contents are left just as 
they were when you started; so this is good for drawing objects if you want 
to erase them afterwards. 

tv:alu-seta Variable 

Set all bits in the affected region. This is not useful with the drawing 
operations, because the exact size and shape of the affected region depend on 
the implementation details of the microcode. The seta function is useful with 
the bitblt operations, where it causes the source rectangle to be transferred 
to the destination rectangle with no dependency on the previous contents of 
the destination. 
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tv:alu-and Variable 

And alu function. Like tv:alu-seta, this is not useful with the drawing 
operations, but can be useful with the bitblt operations. 1 bits in the input 
leave the corresponding output bit alone, and bits in the input clear the 
corresponding output bit. 

12.4.3 Drawing Points on Windows 

:point x y of tv:graphics-mixin Method 

Return the numerical value of the picture element at the specified 
coordinates. The result is or 1 on a black-and-white TV. Clipping is 
performed; if the coordinates are outside the window, the result will be 0. 

:draw-point x y &optional alu value of tv:graphics-mixin Method 

Draw value into the picture element at the specified coordinates, combining it 
with the previous contents according to the specified alu function {value is 
the first argument to the operation, and the previous contents is the second 
argument.) value should be or 1 on a black-and-white TV. Clipping is 
performed; that is, this message will have no effect if the coordinates are 
outside the window, value defaults to -1, that is, a number with as many l's 
as the number of bits in a pixel. 

12.4.4 Copying Bit Rectangles to and From Windows 

rbitblt alu width height from-array from-x from-y to-x to-y of Method 

tvrsheet 
Copy a rectangle of bits from from-array onto the window. The rectangle 
has dimensions width by height, and its upper left corner has coordinates 
(from-x, from-y). It is transferred onto the window so that its upper left 
corner will have coordinates (to-x, to-y). The bits of the transferred rectangle 
are combined with the bits on the display according to the Boolean function 
specified by alu. As in the bitblt function, if from-array is too small it is 
automatically replicated. 

For complete details: See the function bitblt in Reference Guide to 
Symbolics-Lisp, Note that to-array is constrained as described in the the 
description of the bitblt function. See the function 
tv:make-sheet-bit-array, page 121. 

:bitblt-from-sheet alu width height from-x from-y to-array to-x Method 

to-y of tvrsheet 
Copy a rectangle of bits from the window to to-array. All the other 
arguments have the same significance as in the rbitblt method of tv:sheet. 
Note that to-array is constrained as described in the the description of the 
bitblt function. See the function tv:make-sheet-bit-array, page 121. 
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:bitblt-within-sheet alu width height from-x from-y to-x to-y Method 

of tvrsheet 
Copy a rectangle of bits from the window to some other place in the window. 
All the other arguments have the same significance as in the rbitblt method 
of tvrsheet. 

The following function is useful for creating arrays that are bitblt'ed into and out of 
windows. 

tv:make-sheet-bit-array window x y &rest make-array-options Function 

This function creates a two-dimensional bit-array useful for bitblting to and 
from windows. It makes an array whose first dimension is at least x but is 
rounded up so that bitblt's restriction regarding multiples of 32. is met, 
whose second dimension is y, and whose type is the same type as that of the 
screen array of window (or the type it would be if window had a screen 
array), make-array-options are passed along to make-array when the array 
is created, so you can control other parameters such as the area. 

12.4.5 Drawing Characters and Strings on Windows 

:draw-char font char x y &optional alu of tv:sheet Method 

Display the character with code char from font font on the window with its 
upper left corner at coordinates (x, y). This lets you draw characters in any 
font (not just the ones in the font map), and it lets you put them at any 
position without affecting the cursor position of the window. 

:draw-string string from-x from-y &optional (toward-x (1+ Method 

from-x)) (toward-y from-y) (stretch-p nil) 
(font current-font) (alu tv:char-aluO of 
tv:graphics-mixin 

:draw-string draws a character string between two points. It returns the 

location of the last character printed. 

The string can contain either normal printing characters or art-fat-string 
characters with font change codes. The left baseline point of each character 
lies on the line between the two points defined by from-x y from-y and 
toward-x, toward-y. It uses the baseline rather than the upper-left corner to 
ensure that strings with mixed fonts line up properly. 

The string is always written from left to right, starting at the leftmost point, 
regardless of whether that is the first point or the second point. When the 
string is longer than the line between the points, the full string appears 
anyhow. 

toward-x y toward-y Controls the direction in which printing takes place. 

The default values specify ordinary horizontal output. 
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(send (tv:window-under-mouse) 'rdraw-string 
-hi there" 600 50) 

stretch-p Controls the spacing of the characters. When it is nil 

(the default), the characters appear literally, with no 
change to the spacing. Otherwise, the distance 
between the characters is adjusted so that the string 
starts and ends as close to the two points as possible. 

font Specifies the font to use. The default is the current 

font for the window. 

alu Controls how the pixels being drawn combine with 

pixels already in the window. The default is the 
tv:char-aluf for the window. 

This message is useful for placing text at absolute screen positions (as 
opposed to treating the window as a stream), for labelling graphs, or for 
putting text into pictures. 

12.4.6 Drawing Lines on Windows 

:draw-line xl yl x2 y2 &optional alu (draw-end-point t) of Method 

tvrgraphics-mixin 

Draw a line on the window with endpoints (xl, yl) and (x2, y2). If 
draw -end-point is specified as nil, do not draw the last point. This is useful 
in cases such as xoring a polygon made up of several connected line 
segments. 

:draw-lines alu xO yO xl yl ... xn yn of tvrgraphics-mixin Method 

Draw n lines on the screen, the first with endpoints (xO, yO) and (xl, yl), the 
second with endpoints (xl, yl) and (x2, y2), and so on. The points between 
lines are drawn exactly once and the last endpoint, at (xn, yn), is not drawn. 

:draw-dashed-line from-x from-y to-x to-y &optional (alu Method 

tv:char-aluf) (dash-spacing 20J 
space-literally-p (offset 0) dash-length of 
tv:graphics-mixin 
:draw-dashed-line draws a dashed line along the line lying between two 
points. All the dashes are the same length; all the spaces between the 
dashes are the same length. (The spaces, however, need not be the same 
length as the dashes). The spacing and lengths of the dashes are controlled 
by separate arguments. 

alu Controls how the pixels being drawn combine with pixels 

already in the window. The default is the tv:char-aluf 
for the window. 
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dash-spacing Specifies the distance from the beginning of one dash to 

the beginning of the next dash. It is expressed in pixels. 
The default is 20. (The spacing between dashes is 
dash-spacing minus dash-length.) This specifies the 
"frequency" of the line. 

space-literally-p Controls what happens when the distance between the 
points, given the specified spacings, would not produce a 
full-size dash connected to the endpoint. 

The default value, nil, allows the size of dash-spacing to 
be adjusted slightly so that the dashes are all of equal size 
and both endpoints look the same, as far as dash length 
goes. In this case, the dash-length is always exactly half 
of the dash-spacing; any values for offset and dash-length 
are ignored. 

The value t means to use dash-spacing exactly, with no 
adjustment. The endpoint might or might not have a 
dash connected to it, depending on the exact distances 
involved. 

offset Specifies a distance (in pixels) from the starting point 

(from-x, from-y) for the beginning of the first dash. This 
lets you control the "phase" of the dashed line. 

dash-length Specifies the length of the line segments, in pixels. It 

must be less than dash-spacing. This lets you control the 
"duty cycle" of the line. The default is half the value of 
dash-spacing. 

You can make complex dashing by using :draw-dashed-line many times 
with space-literally-p as t. For example: 

(progn 
(send terminal-io *: draw-dashed- line 200. 200. tv:alu-ior 25. 
(send terminal-io * :draw-dashed-line 200. 200. tv:alu-ior 25. 

This gives you alternating long and short dashes. Because the nil value for 
space-literally-p changes the spacing, this technique does not work well when 
space-literally-p is nil. 

:draw-curve x-array y-array feoptional end alu of Method 

tv:graphics-mixin 

Draw a sequence of connected line segments. The x and y coordinates of the 
points at the ends of the segments are in the arrays x-array and y-array. 
The points between line segments are drawn exactly once and the point at 
the end of the last line is not drawn at all; this is especially useful when alu 
is tv:alu-xor. The number of line segments drawn is 1 less than the length 
of the arrays, unless a nil is found in one of the arrays first in which case 
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the lines stop being drawn. If end is specified it is used in place of the 
actual length of the arrays. 

:draw-closed-curve x-array y-array &optional end (alu Method 

tv:char-alufj of tv:graphics-mixin 

:draw-closed-curve draws a sequence of connected line segments, using the 
points in x-array and y-array as the x and y coordinates for the end-points of 
the lines. It ensures that each particular point is drawn only once, which is 
necessary for producing a connected line with tv:alu-xor. It plots the points 
in the arrays until end elements or until it encounters nil in either of the 
arrays. The default for end is the length of x-array. alu specifies how the 
pixels being drawn combine with those already there. It plots the points in 
the arrays until end elements or until it encounters nil in either of the 
arrays. 

:draw-closed-curve is the same as :draw-curve except that it closes the 
figure by joining the first and last points. 

:draw-wide-curve x-array y-array width &optional end alu of Method 

tv:graphics-mixin 
Like rdraw-curve but width is how wide to make the lines. 

12.4.7 Drawing Polygons and Circles on Windows 

:draw-rectangle width height x y &optional alu of tv:sheet Method 

Draw a filled-in rectangle with dimensions width by height on the window 
with its upper left corner at coordinates (x, y). 

:draw-triangle xl yl x2 y2 x3 y3 &optional alu of Method 

tv:graphics-mixin 

Draw a filled-in triangle with its corners at (xl, yl), (x2, y2), and (x3, y3). 

:draw-circle center-x center-y radius &optional alu of Method 

tv:graphics-mixin 

Draw the outline of a circle specified by its center and radius. 

:draw-circular-arc center-x center-y radius start-theta end-theta Method 

&optional (alu tv:char-alufj of 
tv:graphics-mixin 

Draws a circular arc for the circle centered at center-x, center-y with radius 
radius. It draws the part of the circle swept counterclockwise from the 
starting angle to the finishing angle. The angles are assumed to be in 
radians and are reduced mod 2pi before drawing. For example, drawing from 
pi/4 to -pi/4 draws a "C". The same "C" appears when you draw from pi/4 to 
7pi/4. 

For tv:alu-xor, the behavior with respect to points that would fall on the 
same pixel is not defined. 
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:draw-filled-in-circle center-x center-y radius &optional alu of Method 

tv:graphics-mixm 

Draw a filled-in circle specified by its center and radius. 

:draw-filled-in-sector center-x center-y radius theta-1 theta-2 Method 

&optionaI alu of tv:graphics-mixin 
Draw a "triangular" section of a filled-in circle, bounded by an arc of the 
circle and the two radii at theta-1 and theta-2. These angles are in radians; 
an angle of zero is the positive-X direction, and angles increase counter- 
clockwise. 

rdraw-regular-polygon xl yl x2 y2 n &optional alu of Method 

tv:graphics-mixin 

Draw a filled-in, closed, convex, regular polygon of (abs n) sides, where the 
line from (xl, yl) to (x2, y2) is one of the sides. If n is positive then the 
interior of the polygon is on the right-hand side of the edge (that is, if you 
were walking from (xl, yl) to (x2, y2) y you would see the interior of the 
polygon on your right-hand side; this does not mean "toward the right-hand 
edge of the window"). 

12.4.8 Drawing Splines on Windows 

:draw-cubic-spline px py z &optional curve-width alu cl c2 Method 

pl-prime-x pl-prime-y pn-prime-x pn-prime-y 
of tv:graphics-mixin 
Draw a cubic spline curve that passes through a sequence of points. The 
arrays px and py hold the x and y coordinates of the sequence of points; the 
number of points is determined from the active length of px. Through each 
successive pair of points, a parametric cubic curve is drawn with the 
:draw-curve message, using z points for each such curve. If curve-width is 
provided, the :draw-wide-curve message is used instead, with the given 
width. The cubics are computed so that they match in position and first 
derivative at each of the points. At the end points, there are no derivatives 
to be matched, so the caller must specify the boundary conditions, cl is the 
boundary condition for the starting point, and it defaults to '.relaxed; c2 is 
the boundary condition for the ending point, and it defaults to the value of 
cl. The possible values of boundary conditions are: 

rrelaxed 

Make the derivative zero at this end. 

rclamped 

Allow the caller to specify the derivative. The arguments pl-prime-x 
and pl-prime-y specify the derivative at the starting point, and are 
only used if cl is rclamped; likewise, pn-prime-x and pn-prime-y 
specify the derivative at the ending point, and are only used if c2 is 
rclamped. 
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rcyclicMake the derivative at the starting point and the ending point be 
equal. If cl is rcyclic then c2 is ignored. To draw a closed curve 
through n points, in addition to using :cyclic, you must pass in px 
and py with one more than n entries, since you must pass in the first 
point twice, once at the beginning and once at the end. 

: anti-cyclic 

Make the derivative at the starting point be the negative of the 
derivative at the ending point. If cl is ranticyclic then c2 is ignored. 

12.4.9 Primitives for Drawing Onto Arrays 

The following functions are primitives for drawing pictures onto arrays. You should 
only use them on arrays and not directly on windows. 

sys:%draw-rectangle width height x y alu sheet-or-array Function 

This is analogous to the :draw-rectangie message to tv:stream-mixin. 

sys:%draw-line xl yl x2 y2 alu draw-end-point sheet-or-array Function 

This is analogous to the :draw-line message to tv:graphics-mixin. 

sys:%draw-triangle xl yl x2 y2 x3 y3 alu sheet-or-array Function 

This is analogous to the :draw-triangle message to tv:graphics-mixin. 



12.5 Notifications 

12.5.1 Overview of Notifications 

Notifications are messages that a process sends to the user asynchronously to inform 
the user of some change in the state of the process. Some examples: 

• By default the garbage collector notifies the user as storage is used up and 
when the dynamic garbage collector flips and flushes oldspace. 

• If a window's deexposed typeout action is :notify, the user is notified when an 
attempt is made to type out on that window. 

• Converse messages can be received as notifications. 

A process uses tvmotify to notify the user. This function constructs a notification 
and saves it on a queue. A central delivery process takes notifications from the 
queue and delivers them to the user. This process first gives the process associated 
with the selected window a chance to accept the notification itself. If the process 
associated with the selected window does not accept the notification within a short 
time, the delivery process usually tries to display the notification itself, in either the 
selected window or a pop-up window. 



127 
March 1985 Using the Window System 



The notification delivery process tries to give the user process a chance to accept the 
notification by storing the notification in a locative obtained by sending the 
:notification-cell message to the selected window. If the user process wants to 
accept notifications, it usually checks the contents of this cell as part of the 
:input-wait wait function. The user process sends the rreceive-notification 
message to accept the notification. When it wants to display a notification it usually 
calls sysrdisplay-notification. By default, if the user process doesn't accept a 
notification, the notification delivery process displays the notification in a pop-up 
window. The user process can use the with-notification-mode special form to 
control what happens to notifications it doesn't accept. 

All notifications received since cold booting are displayed in a scroll window obtained 
by pressing SELECT N or by calling display-notifications. You can display some or 
all notifications by using the Show Notifications command. 

display-notifications Function 

Selects a scroll window that displays all notifications received since cold 
booting. 

12.5.2 Notifying the User 

tv:notify window-of-interest format-control &rest format-args Function 

Issues an asynchronous notification to the user. Constructs a notification 
and pushes it onto a queue. A central notification delivery process delivers 
the notification to the user. The text of the notification is constructed from 
format-control and format-args. If window-of-interest is not nil, it is a 
window to be made available via function s. 

12.5.3 Receiving and Displaying Notifications 

When a process notifies the user, the central notification delivery process gives the 
process associated with the selected window a chance to accept the notification before 
the delivery process tries to display the notification itself. The notification delivery 
process stores the notification in a locative obtained by sending the 
:notification-cell message to the selected window, unless a notification is already 
there. In that case the notification delivery process usually tries to display the 
notification itself. 

A user process that wants to accept notifications should send the selected window a 
:notification-cell message to find the locative that might contain a notification. 
The process should wait (usually in an :input-wait wait function) until the locative 
contains something other than nil. 

When a notification cell contains a notification, a process can accept the notification 
by sending the selected window a :receive-notification message. If the process 
wants to display the notification, it usually passes it on to the function 
sysrdisplay-notifications. 
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:notification-cell Message 

This message to an interactive stream returns the locative in which the 
notification delivery process stores notifications. If some process notifies the 
user, the notification delivery process gives the process associated with the 
selected window a chance to accept the notification. It does this by trying to 
store the notification in the locative returned by the :notification-cell 
message to the selected window, unless the locative contains a notification 
already. In that case the notification delivery process usually tries to display 
the notification itself. 

A user process that wants to accept notifications should find this locative by 
sending the :notification-cell message to the selected window. It should 
wait (usually in an :input-wait wait function) for the locative to contain 
something other than nil. The user process can receive the notification by 
sending the selected window a rreceive-notification message. 

rreceive-notification Message 

This message to an interactive stream returns a notification when one exists 
in the stream's notification cell. The message checks the contents of the 
locative returned by the :notification-cell message to the stream. When 
the locative contains a notification, rreceive-notification returns the 
notification and stores nil in the locative. When the locative does not contain 
a notification, rreceive-notification returns nil. 

sys:display-notification stream note &optional style window-width Function 

Displays a notification on stream, note is the notification, returned by the 
rreceive-notification message to an interactive stream. The display 
includes the time and the text of the message as specified in the arguments 
to tv:notify. 

style is nil or a keyword determining the style of the display: 

nil Displays the time and the text of the message at the 

current cursor position, with indentation. This is the 
default. 

rstream Sends a :fresh-line message, then displays the time and 

the text of the message, with indentation, in square 
brackets, then displays a Newline. This style is for 
merging the notification display with other output to the 
stream. 

:window Sends a rfresh-line message, then displays the time and 

the text of the message, with indentation, in square 
brackets. This style is for using the entire window to 
display the notification. It assumes the window has been 
cleared first. 
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:pop-up Displays the time and the text of the message at the 

current cursor position, with indentation, then sends a 
:fresh-line message. This style is used by the notification 
delivery process to display notifications in a pop-up window. 

window-width is nil or the number of characters available on a line to display 
the notification. If window-width is nil or not supplied, the default is the 
result of sending the stream a :size-in-characters message. This is used 
only to determine how much to indent lines other than the first in the 
notification. If window-width is about 110 or more, lines are indented to the 
beginning of the text of the message (following the time). If window-width 
is about 100 or less, lines are indented only one character. You can supply a 
large window-width to increase the indentation in a narrow window, or 
supply a small window-width to decrease the indentation in a wide window. 

If style is :stream, twindow, or :pop-up and if a "window of interest" was 
supplied as the first argument to tvmotify, a message is displayed that 
informs the user that FUNCTION e s selects the window of interest. 

sys:display-notification does not return any interesting values, unless style 
is :pop-up. In that case it returns the X and Y coordinates, in pixels, of the 
beginning of the line following the text of the notification. 

Following is a simple example of a command loop that waits for input, a notification, 
or a new selected-pane. When a notification arrives, it displays it in a pane reserved 
for notifications. When input arrives, it just displays a representation of the input 
in the selected pane. 
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(defun my- top- level (frame) 
(let ((notification-pane (send frame :get-pane 'notification-pane))) 
(error-restart- loop ((error sysrabort) "My top level") 
(let ((selected-pane (send frame :selected-pane)) 
(note)) 
(when selected-pane 
(send selected-pane : input-wait nil 
#*( lambda (note-cell) 

(declare (sys: downward- function)) 
(or (neq selected-pane (send frame :selected-pane)) 
(not (null (location-contents note-cell))))) 
(send selected-pane motification-cell)) 
(cond ((neq selected-pane (send frame :selected-pane))) 

((setq note (send selected-pane treceive-notification)) 
(sysrdisplay-notification notification-pane note :stream)) 
(t 

(let ((char (send selected-pane :any-tyi-no-hang))) 
(cond ((null char)) 
((fixp char) 

(format selected-pane "~&Character: ~C" char)) 
((listp char) 

(format selected-pane "~&Blip: ~S" char)) 
(t (format selected-pane "~&Unknown object: ~S" char))))))))))) 

After storing a notification in the selected window's notification cell, the notification 
delivery process gives the process associated with the selected window some time to 
accept the notification. The amount of time is determined by the variable 
tv:*notification-deliver-timeout*. 

tv:*notification-deliver-timeout* Variable 

The length of time, in sixtieths of a second, that the notification delivery 
process waits for the process associated with the selected window to accept a 
notification. If the selected window's process does not accept the notification 
during this time, the delivery process takes the notification back and usually 
tries to display it itself. Default: 180. (three seconds). 

If the process associated with the selected window does not accept a notification 
within the specified time, or if the window's notification cell already contains a 
notification, the window's notification mode determines what the delivery process 
does with the notification. You can use the motification-mode message to get the 
notification mode and the :set-notification-mode message to set it. 

motification-mode Message 

This message to an interactive stream returns the stream's notification mode. 
The notification mode determines what the notificationr delivery process does 
with a notification when the process associated with the stream doesn't 
accept it: 
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:pop-up 

:blast 
xignore 

nil 



The notification is displayed in a pop-up window. This is 
the default. 

The notification is displayed on the stream. 

The notification is ignored but is added to the notification 
history for SELECT N and the Show Notifications command. 

The same as :pop-up. 



:set-notification-mode new-mode Message 

This message to an interactive stream sets the stream's notification mode. 
The notification mode determines what the notification delivery process does 
with a notification when the process associated with the stream doesn't 
accept it. new-mode can be a keyword or nil: 



:pop-up 

rblast 
rignore 

nil 



The notification is displayed in a pop-up window. This is 
the default. 

The notification is displayed on the stream. 

The notification is ignored but is added to the notification 
history for SELECT N and the Show Notifications command. 

The same as :pop-up. 



If you want to execute some code with a stream's notification mode bound to some 
value, use the special form with-notification-mode. 

with-notification-mode (new-mode &optional stream) &body body Special Form 
Executes body with the notification mode of stream bound to new-mode, 
stream defaults to standard-output. The notification mode determines what 
the notification delivery process does with a notification when the process 
associated with stream doesn't accept it. new-mode can be a keyword or nil: 



:pop-up 

rblast 
rignore 

nil 



The notification is displayed in a pop-up window. This is 
the default. 

The notification is displayed on the stream. 

The notification is ignored but is added to the notification 
history for SELECT n and the Show Notifications command. 

The same as :pop-up. 



12.5.3.1 Pop-up Notifications 

When a notification is displayed in a pop-up window, the user is alerted with a beep 
and given some time to notice the beep and stop typing. Until that time elapses, all 
typein is directed to the previously selected window, except that the user can press 
abort to deexpose the pop-up window immediately. The amount of time is 
determined by the variable tv:unexpected-select-delay. 
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tv:unexpected-select-delay Variable 

The amount of time, in sixtieths of a second, that a user is given to notice a 
pop-up notification and stop typing. Until that time has elapsed, all typein is 
directed to the previously selected window. During this time the user can 
press RBORT to deexpose the pop-up window. A value of nil means no delay 
time and no display of the message that typing any character deexposes the 
pop-up window. Default: 180. (three seconds). 

After the select delay, typing any character or selecting another window deexposes 
the pop-up window. If a "window of interest" was supplied as the first argument to 
tv:notity, a message is displayed that informs the user that function e s or a 
mouse click on the pop-up window selects the window of interest. If another 
notification arrives while the pop-up window is exposed, the notification is displayed 
on the window. If after a time the user has typed nothing, the pop-up window is 
deexposed automatically. The amount of time the pop-up window remains exposed is 
determined by the variable tv:*notification-pop-down-delay*. 

tv:*notification-pop-down-delay* Variable 

The amount of time, in sixtieths of a second, that a notification pop-up 
window remains exposed if the user types no characters to the window. A 
value of nil means that the window remains exposed indefinitely. Default: 
54000. (15 minutes). 



12.6 Input From Windows 

12.6.1 Windows as Input Streams 

A window can be used as if it were the keyboard of a computer terminal, and it can 
act as an input stream. The flavor tv:stream-mixin implements the messages of 
the Lisp Machine input stream protocol. The tv:stream-mixin flavor is a 
component of the tvtwindow flavor. 

tv:stream-mixin Flavor 

This flavor allows a window to function as an interactive stream. It should 
be mixed into any window that can be used for interacting with a user, and 
particularly into any window that can become the value of terminal-io. It 
gives the window an I/O buffer, allows the window to handle input messages, 
and provides the window with input editing. 

tv:stream-mixhi includes sitinteractive-stream, and windows support all the 
operations that interactive streams in general do: See the section "Interactive 
Streams", page 1. Windows have specialized versions of some input operations: See 
the section "Messages for Input From Windows", page 134. 

The reason you do input from windows rather than just from the keyboard is so 
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that many programs can share the keyboard without getting in each other's way. If 
two processes try to read from the keyboard at the same time, they can do it by 
going through windows. Characters from the keyboard go only to the selected 
window, and not to any of the others; this way, you can control which process you 
are typing at, by selecting the window you are interested in. 

If a process tries to do input from a window that does not have any characters in its 
input buffer, what happens depends on the window's deexposed typein action. It 
may be either :normal or motify. If the deexposed typein action is mormal, 
and/or the window is exposed, then the process just waits until something appears in 
the input buffer. If the deexposed typein action is tnotify and the window is not 
exposed, then the user is notified with a message like "Process X wants typein", and 
the window is "made interesting" so that FUNCTION s can select it. 

Reading characters from a window normally returns an integer that represents a 
character in the Lisp Machine character set, possibly with extra bits that correspond 
to the control, METfl, SUPER, and hyper keys. For information on the format of such 
integers and the symbolic names of the bit fields: See the section "The Character 
Set" in Reference Guide to Streams, Files, and I/O. 

Note that reading characters from a window does not echo the characters; it does 
not type them out. If you want echoing, you can echo the characters yourself, or 
call the higher-level functions such as tyi, read, and readline; these functions 
accept a window as their stream argument and will echo the characters they read. 

Every window (that has tv:stream-mixin as a component) has an I/O buffer that 
holds characters that are typed by the user before any program reads the characters. 
When you type a character, it enters this buffer, and stays there until a program 
tries to read characters from this window. There are some messages below that deal 
with the I/O buffer, letting you clear it and ask whether there is anything in it. 

Normally, integers get into the I/O buffer because characters were typed on the 
keyboard. However, you can also get any Lisp object into a window's I/O buffer 
under program control, by sending a :force-kbd-input message to the window. 
One common use of this feature is for the mouse process to tell a user process about 
activity on the mouse buttons. That is how characters with the %%kbd-mouse bit 
can get read from the window. It is possible to put Lisp objects other than integers 
into an I/O buffer; by convention, such objects are usually lists whose first element 
is a symbol saying what kind of a "message" this object is. (Such lists are 
sometimes called blips.) You can also get the mouse to send blips instead of 
integers, in order to find out the mouse position at the time of the click. Using the 
mouse is explained later on. 

You can explicitly manipulate I/O buffers in order to get certain advanced 
functionality, by using the :io-buffer init option and the :io-buffer and 
:set-io-buffer messages. One thing you can do is to make several windows use the 
same I/O buffer; this is often used to make panes of a paned window all share the 
same I/O buffer. Another thing you can do is put properties on the I/O buffer's 
property list; this lets you request various special features. 
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The console hardware actually sends codes to the Lisp Machine whenever a key is 
depressed or lifted; thus, the Lisp Machine knows at all times which keys are 
depressed and which are not. You can use the tv:key-state function to ask 
whether a key is down or up. Also, you can arrange for reading from a window to 
read the raw hardware codes exactly as they are sent, by putting a non-nil value of 
the :raw property on the property list of the I/O buffer; however, the format of the 
raw codes is complicated and dependent on the hardware implementation. It is not 
documented here. 

The window system intercepts some characters specially. Some are intercepted when 
the user process is about to read the character from a window; others are 
intercepted as soon as they are typed. In the first category, the 
io-buffer-output-function of the I/O buffer defaults to 

tvikbd-default-output-function, which intercepts certain characters when they are 
read. The value of the variable sys:kbd-intercepted-characters is a list of 
characters that are intercepted and not returned as input from the window. These 
characters default to #\abort, #\m-abort, #\suspend, and #\m-suspend. For 
more information: See the section "Intercepted Characters", page 15. 

The second category of specially handled characters is those handled asynchronously. 
See the section "Asynchronous Characters", page 139. 

12.6.2 Messages for Input From Windows 

Windows support all the input operations that interactive streams in general do: See 
the section "Messages for Input From Interactive Streams", page 11. Windows have 
specialized versions of some of these operations, mainly involved in reading characters 
from I/O buffers. 

:any-tyi &optional eof-action of tv:stream-mixin Method 

Read and return the next character of input from the window, waiting if 
there is none. Where the character comes from depends on the value of the 
variable rubout-handler. Following is a summary of actions for each 
possible value of rubout-handler: 

nil If the input buffer contains unscanned input, take the 

next character from there. Otherwise, take the next 
character from the window's I/O buffer. 

:read If the input buffer contains unscanned input, take the 

next character from there. Otherwise, if an activation blip 
or character is present, return that. Otherwise, enter the 
input editor. 

:tyi Take the next character from the window's I/O buffer. 

If eof-action is not nil, an error is signalled when an end-of-file is 
encountered. Otherwise, the method returns nil when an end-of-file is 
encountered. The default for eof-action is nil. 
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:any-tyi-no-hang &optional eof-action of tv:stream-mixin Method 

Check the window's I/O buffer and return the next character if it is 
immediately available. If no characters are immediately available, return nil. 
It is an error to call this method from inside the input editor (that is, if the 
value of rubout-handler is not nil), eof-action is ignored. This is used by 
programs that continuously do something until a key is typed, then look at 
the key and decide what to do next. 

:untyi ch of tv:stream-mixin Method 

Return ch to the proper buffer so that it will be the next character returned 
by :any-tyi or :tyi. ch must be the last character that was rtyi'ed, and it is 
illegal to do two runtyi's in a row. Where ch is put depends on the value of 
the variable rubout-handler. Following is a summary of actions for each 
possible value of rubout-handler: 

nil If the input buffer contains scanned input, decrement the 

scan pointer. Otherwise, put ch back into the window's 
I/O buffer. 

tread Decrement the input editor scan pointer. 

:tyi Put ch back into the window's I/O buffer. 

This method is used by parsers that look ahead one character, such as read. 

rlisten of tv:stream-mixin Method 

Return t if there are any characters available to :any-tyi or :tyi, or nil if 
there are not. For example, the editor uses this to defer redisplay until it 
has caught up with all of the characters that have been typed in. 

:clear-input of tv:stream-mixm Method 

Clear this window's input and I/O buffers. This flushes all the characters 
that have been typed at this window, but have not yet been read. 

12.6.3 SELECT and function Keys 

tv:add-function-key char function documentation &rest options Function 

Adds char to the list of keys that can follow the FUNCTION key. Following is 
an explanation of the arguments: 

char The character (an integer) that should be typed after 

FUNCTION to get the new command. Lower-case letters are 
converted to upper case. 

function A specification for the action to be taken when the user 

presses function char, function can be a symbol or a list: 

• Symbol: The name of a function to be applied to one 
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argument. The argument is the numeric argument 
to FUNCTION char (an integer) or nil if the user 
supplied none. 



• List: A form to be evaluated. 

function is applied or evaluated in a newly created process 
unless you supply the :keyboard-process option (see 
below). 

documentation A form to be evaluated when the user presses 

FUNCTION HELP to produce documentation for the command. 
The form should return a string, a list of strings, or nil 
(of course, documentation can just be a string or nil): 

• String: One line of text describing this command for 

FUNCTION HELP. 

• List of strings: Each string is a line of text for 
function help to print successively in describing this 
command. Usually documentation is a Lisp form that 
looks like '("line 1" "line 2" ...). 

• nil 

function help prints nothing describing this 
command. 

options A series of alternating keywords and values. Possible 

options are :keyboard-process, :process-name, 
rprocess, and rtypeahead: 

• rkeyboard-process 

function is applied or evaluated in the keyboard 
process instead of a newly created process. This 
option exists because certain built-in commands must 
run in the keyboard process. You should not use 
this option for new commands. The cost of creating 
a new process is quite low. 

• :process-name string 

string is the l ^me of the newly created process in 
which function is applied or evaluated. If you don't 
supply this option or the rprocess option, the name 
of the process is "Function Key". 

• rprocess list 

list is a list to be used as the first argument to 
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process-run-function, called to create a new process 
in which function is applied or evaluated. This 
option takes precedence over :process-name. 

• ttypeahead 

Everything the user types before pressing the 
FUNCTION key is treated as typeahead to the currently 
selected window. Use this option with commands 
that change windows to ensure that the user's typed 
input goes to the I/O buffer of the expected window. 

Here is an example of a call to tv:add-function-key: 

(tv: add- function- key #\refresh 'tv:kbd-screen-redisplay 
"Clear and redisplay all windows.") 

See the variable tv:*function-keys*, page 137. 

tv:*function-keys* Variable 

The value of this variable is an alist, each entry of which describes a 
subcommand of the FUNCTION key. Entries are of the form: 

(char function documentation optionl option2 ...) 

For an explanation of the components of the entries: See the function 
tv:add-function-key, page 135. Use tv:add-function-key to add a new 
entry or redefine an existing one rather than changing the value ot 
tv:*function-keys* yourself. 

tv:add-select-key char flavor name &optional (create-p t) Function 

Adds char to the list of keys that can follow the SELECT key. Following is an 
explanation of the arguments: 

char The character (an integer) that should be typed after 

SELECT to get the new command. Lower-case characters 
are converted to upper case. 

flavor A specification for the window to be selected when the 

user presses SELECT char, flavor can be a symbol, an 
instance, or a list: 

• Symbol: The name of a flavor. The SELECT 
command searches the list of previously selected 
windows and selects a window of flavor flavor if it 
finds one. (flavor can be the name of a component 
flavor of the window, not just the instantiated 
flavor.) Otherwise, if the currently selected window 
is of flavor flavor t it beeps. Otherwise, it takes the 
actions specified by create-p. 
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• Instance: A window. The SELECT command selects 
that window. 

• List: A form to be evaluated (in the SELECT 
command's newly created process). The form should 
return a window to be selected or a symbol that is 
the name of a flavor of window to be selected. 

name A string giving the colloquial name of the program to be 

selected, name is printed by SELECT HELP. 

create-p A specification for actions that the SELECT command should 

take if it cannot find a previously selected window of flavor 
flavor and if the currently selected window is not of flavor 
flavor, create-p can be nil, t, another symbol, or a list: 

• nil: Beeps. 

• t: Calls tv:make-window with no options to create 
a window of flavor flavor. Selects that window. 

• Another symbol: The name of a flavor. Calls 
tv:make-window with no options to create a 
window of flavor create-p. Selects that window. 

flavor and create-p can be names of different flavors. 
For example, flavor might be the name of a mixin 
that is a component of several flavors, all of which 
are suitable flavors of window to select. 

• List: A form to be evaluated (in the SELECT 
command's newly created process). The form 
presumably selects a window. 

If the user presses char with the c- modifier (after pressing SELECT), and if 
flavor is a symbol that names a flavor or is a form that returns the name of 
a flavor, the SELECT command does not search for previously selected windows 
of flavor flavor. Instead, it takes the actions specified by create-p. But if 
flavor is a window, the SELECT command selects that window even if the user 
presses char with the c- modifier. 

Here is an example of a call to tv:add-select-key: 

(tv:add-select-key #/E 'zwei :zmacs- frame "Editor") 

See the variable tv:*select-keys*, page 139. 
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tv:*select-keys* Variable 

The value of this variable is an alist, each entry of which describes a 
subcommand of the select key. Entries are of the form: 

{char flavor name create-p) 

For an explanation of the components of the entries: See the function 
tv:add-select-key, page 137. Use tv:add-select-key to add a new entry or 
redefine an existing one rather than changing the value of tv:*select-keys* 
yourself. 

12.6.4 Asynchronous Characters 

The FUNCTION and SELECT keys are always intercepted as soon as they are typed; 
they cause the Keyboard process to take special action to handle the command that 
the user is giving. You can add your own function and select commands, using 
the functions tv:add-function-key and tv:add-select-key. See the section "SELECT 
and FUNCTION Keys", page 135. 

Other characters can also be intercepted as soon as they are typed. A special system 
process called the keyboard process calls a user-defined function as soon as the key is 
pressed. The main process of the program is left undisturbed. This function runs 
in parallel with the main program and could communicate with it. 

Asynchronous character handling is available to any window that includes 
tv:stream-mixin. The window has a list that associates keyboard characters with 
functions. The default list contains c-RBORT, c-suspend, c-n-RBORT, and 
c-n-SUSPEND. The default actions are the same as those of the corresponding keys 
without c- modifiers, except that the window's process is sent an interrupt 
message so that the actions take place immediately. 

The keyboard process checks each character coming in to see if it is defined as an 
asynchronous character for the selected window. When it is, the keyboard process 
calls the associated function in the context of the keyboard process. 

The function that runs as a result of an asynchronous character is running in the 
keyboard process. It is called with two arguments, the character and self. It 
should be very short and must not do any I/O. An error in one of these functions 
would break the keyboard process and the keyboard along with it and you would 
have to warm boot. To avoid any possibility of errors, you can have the function 
create a new process with process-run-function and make the new process handle 
the real work. 

You can set up your own handling of asynchronous characters by using the 
:asynchronous-character-p, :handle-asynchronous-character, 
:add-asynchronous-character, and :remove-asynchronous-character messages 
and the rasynchronous-characters init option for sitinteractive-stream. See the 
section "Interactive-stream Operations for Asynchronous Characters", page 17. 
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12.7 TV Fonts 

12.7.1 Using TV Fonts 

On the Symbolics Lisp Machine, characters can be typed out in any of a number of 
different typefaces. Some text is printed in characters that are small or large, 
boldface or italic, or in different styles altogether. Each such typeface is called a 
font . A font is conceptually an array, indexed by character code, of pictures showing 
how each character should be drawn on the screen. The Font Editor (FED) is a 
program that allows you to create, modify, and extend fonts. 

A font is represented inside the Lisp Machine as a Lisp object. Each font has a 
name. The name of a font is a symbol, usually in the fonts package, and the 
symbol is bound to the font. A typical font name is tr8. In the initial Lisp 
environment, the symbol fonts:tr8 is bound to a font object whose printed 
representation is something like: 

#<FONT TR8 23471 2342> 

The initial Lisp environment includes many fonts. Usually there are more fonts 
stored in BFD files in file computers. New fonts can be created, saved in BFD files, 
and loaded into the Lisp environment; they can also simply be created inside the 
environment. 

Drawing of characters in fonts is done by microcode and is very fast. The internal 
format of fonts is arranged to make this drawing as fast as possible. This format is 
described later, but you almost certainly do not need to worry about it. 

You can control which font is used when output is done to a window. Every 
window has a font map and a current font. The font map is conceptually an array 
of fonts; with a small nonnegative number, the font map associates a font. The 
current font of a window is always one of the fonts in the window's font map. 
Whenever output is done to a window, the characters are printed in the current 
font. You can change the font map and the current font of a window at any time 
by sending the appropriate messages. 

Before we go into the details of these messages, there is a little issue to clear up. 
Different kinds of screen require different kinds of fonts. The two kinds of screens 
currently supported are black-and-white screens with one bit per pixel, and color 
screens with four bits per pixel. Color screens with eight bits per pixel will certainly 
be supported in the near future, and other kinds of screen may appear. However, it 
is nice to be able to write programs that will work no matter what screen their 
window is created on. The problem is that if you write a program that specifies 
which fonts to use by actually naming specific fonts, then the program will only 
work if the window that you are using is on the same kind of screen that the fonts 
you are using has been designed for. 

To solve this problem, a program does not have to specify the actual font to be used. 
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Instead, it specifies a certain symbol that stands for a whole collection of fonts. All 
of these fonts are the same except that they work on different kinds of screens. 
The symbol that you use is the name of the member of the collection that works on 
the black-and-white screen. In other words, when you want to specify a font, 
always use the name of a black-and-white font rather than a font itself. Every 
screen knows how to understand these symbols and find an appropriate font to use. 
This symbol is called a font descriptor, because it describes a font rather than 
actually being a font. 

In the messages below, where the message expects to be passed a font descriptor, 
you normally pass a symbol as explained above. You may also pass in a font, in 
which case the symbol that names that font will be used as the font descriptor. In 
other words, if you pass in a font explicitly, that font itself might not be used; if you 
pass in a black-and-white font to a window on a color screen, the name of the black- 
and-white font will be used as a font descriptor and a color version of the font will 
be found. 

The functions that understand font descriptors have some cleverness in order to 
make life easier for you. If you pass in the name of a font that is not loaded into 
the Lisp environment, an attempt will be made to load it from the file server, using 
the name of the font as the name of the file, leaving the version and type 
unspecified, using the load function. Also, the color screen knows how to create 
color versions of fonts on the fly if they do not already exist. Either of these things 
may make your program run slowly the first time you run it, and so, if you care, 
you can load the file yourself, and create a color version of the font yourself. 

Every screen has a default font. When a window is created, by default, all elements 
of its font map are this default font, and the current font is this font. 

12.7.2 Font Messages to Windows 

:font-map of tvrsheet Method 

Returns the font map of the window. The object returned is the array that 
is actually being used to represent the font map inside the window. You 
should not alter anything about this array, since the window depends on it in 
order to function correctly. To change the font map, use the :set-font-map 
message. 

:set-font-map new-map of tvrsheet Method 

Set the font map to contain the fonts given in new-map. Return the array 
of fonts that actually represents the font map inside the window (don't mess 
with this array!), new-map may be an array of font descriptors, in which 
case this array is installed as the new internal array of the window, and the 
font descriptors are replaced by fonts, new-map may also be a list of font 
descriptors, in which case the array is created from the list in the style of 
fillarray, with the last element of the list filling in the remaining elements 
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of the array if any (the array is made at least 26. elements long, or long 
enough to hold all the elements of the list). If new-map is nil, all the 
elements of the map are set to the default font of the screen. The current 
font is set to zero (the first font in the list or array). The line height and 
baseline of the window are adjusted appropriately. 

:set-font-map-and-vsp new-map new-vsp of tv:sheet Method 

Changes the font map and vsp of the window. 

new-map can be an array of font descriptors or a list of font descriptors, as 
with the argument to the :set-font-map message. However, if the new-map 
argument to :set-font-map-and-vsp is nil, the font map is not changed. 

new-vsp is an integer representing the new vsp, or nil, meaning not to 
change the vsp. 

:font-map new-map (for tvrsheet) Init Option 

This option lets you initialize the font map. new-map is interpreted the 
same way it is interpreted by the :set-font-map message. 

:current-font of tvrsheet Method 

Returns the current font, as a font object. 

:set-current-font new-font of tv:sheet Method 

Set the current font of the window, new-font may be a number, in which 
case that element of the font map becomes the current font. It may also be 
a font descriptor, in which case the font that the descriptor describes is used, 
unless that font is not in the font map, in which case an error is signalled. 
You may only select a font that is already in the font map. 

:baseline of tvrsheet Method 

Returns the maximum baseline of all the fonts in the font map. The bases 
of all characters will be so aligned as to be this many pixels below the top of 
the line on which the characters are printed. In other words, when a 
character is drawn, it will be drawn below the cursor position, by an amount 
equal to the difference between this number and the baseline of the font of 
the character. 

12.7.3 Standard TV Fonts 

You can use Show Font HELP in the Lisp Listener or the List Fonts (n-X) command in 
Zmacs to get a list of all the fonts that are currently loaded into the Lisp 
environment. The fonts package contains the names of all fonts. Here is a list of 
some of the useful fonts: 

fonts:cptfont This is the default font, used for almost everything. 

fonts:jessl4 This is the default font in menus. It is a variable- 
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fonts:cptfonti 

fontsrcptfontcb 

fonts:medfht 

fontsrmedfnb 

fonts:hll2i 
fontsitrlOi 
fonts:hllO 
fonts:hllOb 



width rounded font, slightly larger and more attractive 
than medfnt. 

This is a fixed-width italic font of the same width and 
shape as fontsrcptfont, the default screen font. It is 
most useful for italicizing running text along with 
fonts:cptfont. 

This is a fixed-width bold font of the same width and 
shape as fontsrcptfont, the default screen font. 

This is a fixed-width font with characters somewhat 
larger than those of cptfont. 

This is a bold version of medfnt. When you use Split 
Screen, for example, the [Do It] and [Abort] items are 
in this font. 

This is a variable-width italic font. It is useful for italic 
items in menus; Zmail uses it for this in several menus. 

This is a very small italic font. It is the one used by 
the Inspector to say "More above " and "More below ". 

This is a very small font used for nonselected items in 
Choose Variable Values windows. 

This is a bold version of hllO, used for selected items in 
Choose Variable Values windows. 



12.7.4 Attributes of TV Fonts 

Fonts, and characters in fonts, have several interesting attributes. 

Character Height Font Attribute 

One attribute of each font is its character height. This is a nonnegative integer 
used to figure out how tall to make the lines in a window. Each window has a 
certain line height. The line height is computed by examining each font in the font 
map, and finding the one with the largest character height. This largest character 
height is added to the vertical spacing (in pixels) between the text lines (vsp) 
specified for the window, and the sum is the line height of the window. The line 
height, therefore, is recomputed every time the font map is changed or the vsp is 
set. This ensures that any line has enough room to display the largest character of 
the largest font and still leave the specified vertical spacing between lines. One 
effect of this is that if you have a window that has two fonts, one large and one 
small, and you do output in only the small font, the lines are still spaced far enough 
apart to accommodate characters from the large font. This is because the window 
system cannot predict when you might, in the middle of a line, suddenly switch to 
the large font. 
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Baseline Font Attribute 

Another attribute of a font is its baseline. The baseline is a nonnegative integer 
that is the number of raster lines between the top of each character and the base of 
the character. (The base is usually the lowest point in the character, except for 
letters that descend below the baseline, such as lowercase p and g.) This number is 
stored so that when you are using several different fonts side-by-side, they are 
aligned at their bases rather than at their tops or bottoms. So when you output a 
character at a certain cursor position, the window system first examines the baseline 
of the current font, then draws the character in a position adjusted vertically to 
make the bases of the characters all line up. 

Character Width Font Attribute 

The character width can be an attribute either of the font as a whole, or of each 
character separately. If there is a character width for the whole font, it is as if each 
character had that character width separately. The character width is the amount 
by which the cursor position should be moved to the right when a character is 
output on the window. This can be different for different characters if the font is a 
variable-width font, in which a W might be much wider than an i. Note that the 
character width does not necessarily have anything to do with the actual width of 
the bits of the character (although it usually does); it is merely defined to be the 
amount by which the cursor should be moved. 

Left Kern Font Attribute 

The left kern is an attribute of each character separately . Usually it is zero, but it 
can also be a positive or negative integer. When the window system draws a 
character at a given cursor position, and the left kern is nonzero, the character is 
drawn to the left of the cursor position by the amount of the left kern, instead of 
being drawn exactly at the cursor position. In other words, the cursor position is 
adjusted to the left by the amount of the left kern of a character when that 
character is drawn, but only temporarily; the left kern only affects where the single 
character is drawn and does not have any cumulative effect on the cursor position. 

Fixed-width Font Attribute 

A font that does not have separate character widths for each character and does not 
have any nonzero left kerns is called a fixed-width font. The characters are all the 
same width and so they line up in columns, as in typewritten text. Other fonts are 
called variable-width because different characters have different widths and things do 
not line up in columns. Fixed-width fonts are typically used for programs, where 
columnar indentation is used, while variable-width fonts are typically used for 
English text, because they tend to be easier to read and to take less space on the 
screen. 
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Blinker Width and Blinker Height Font Attributes 

The blinker width and blinker height are two nonnegative integers that tell the 
window system an attractive width and height to make a rectangular blinker for 
characters in this font. These attributes are completely independent of all other 
attributes and are only used for making blinkers. Using a fixed width blinker for a 
variable-width font causes problems; the editor actually readjusts its blinker width as 
a function of what character it is on top of, making a wide blinker for wide 
Characters and a narrow blinker for narrow characters. The easiest thing to do is 
to use the blinker width as the width of the blinker. This works well with a fixed- 
width font. 

Chars-exist-table Font Attribute 

The chars-exist-table is nil if all characters exist in a font, or an art-boolean array. 
This table is not used by the character-drawing software; it is for informational 
purposes. Characters that do not exist have pictures with no bits "on" in them, just 
like the Space character. Most fonts implement most of the printing characters in 
the character set, but some are missing some characters. 

12.7.5 Format of TV Fonts 

The array leader of a font is a structure defined by defstruct. Here are the names 
of the accessors for the elements of the array leader of a font. 

font-name font Function 

The name of the font. This is a symbol whose binding is this font, and 
which serves to name the font. The print-name of this symbol appears in 
the printed representation of the font. 

font-char-height font Function 

The character height of the font; a nonnegative integer. 

font-char-width font Function 

The character width of the characters of the font; a nonnegative integer. If 
the font-char-width-table of this font is non-nil, then this element is 
ignored except that it is used to compute the distance between horizontal tab 
stops; it would typically be the width of a lower-case "m". 

font-baseline font Function 

The baseline of this font; a nonnegative integer. 

font-char-width-table font Function 

If this is nil then all the characters of the font have the same width, and 
that width is given by the font-char-width of the font. Otherwise, this is 
an array of nonnegative integers, one for each logical character of the font, 
giving the character width for that character. 
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font-left-kern-table font Function 

If this is nil then all characters of the font have zero left kern. Otherwise, 
this is an array of integers, one for each logical character of the font, giving 
the left kern for that character. 

font-blinker-width font Function 

The blinker width of the font. 

font-blinker-height font Function 

The blinker height of the font. 

font-chars-exist-table font Function 

This is nil if all characters exist in the font, or an art-boolean array with 
one element for each character of the file. The element is t if the character 
exists and nil if the character does not exist. 

font-raster-height font Function 

The raster height of the font; a positive integer. 

font-raster-width font Function 

The raster width of the font; a positive integer. 

font-indexing-table font Function 

If this is nil, then no characters of this font are wider than thirty-two bits. 
Otherwise, this is the font indexing table of the font, an array with one 
element for each logical character plus one more at the end (to show where 
the last character stops) containing physical character numbers. 



12.8 Blinkers 

Each window can have any number of blinkers. The kind of blinker that you see 
most often is a blinking rectangle the same size as the characters you are typing; 
this blinker shows you the cursor position of the window. In fact, a window can 
have any number of blinkers. They need not follow the cursor (some do and some 
don't); the ones that do are called following blinkers; the others have their position 
set by explicit messages. 

Also, blinkers need not actually blink; for example, the mouse arrow does not blink. 
A blinker's visibility may be any of the following: 

:blink The blinker should blink on and off periodically. The rate at which it 

blinks is called the half-period, and is an integer giving the number of 
60ths of a second between when the blinker turns on and when it 
turns off. 

:on or t The blinker should be visible but not blink; it should just stay on. 
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:off or nil The blinker should be invisible. 

Usually only the blinkers of the selected window actually blink; this is to show you 
where your typein will go if you type on the keyboard. The way this behavior is 
obtained is that selection and deselection of a window have an effect on the visibility 
of the window's blinkers. 

When the window is selected, any of its blinkers whose visibility is :on or :off has 
its visibility set to :blink. Blinkers whose visibility is t or nil are unaffected (that is 
the difference between t and :on, and between nil and toff); blinkers whose 
visibility is rblink continue to blink. 

Each blinker has a deselected visibility, which should be one of the symbols above; 
when a window is deselected, the visibilities of all blinkers that are blinking (whose 
visibility is currently :blink) are set to the deselected visibility. 

Most often, blinkers have visibility :on when their window is not selected, and 
visibility rblink when their window is selected. In this case, the deselected visibility 
is :on. 

Blinkers are used to add visible ornaments to a window; a blinker is visible to the 
user, but while programs are examining and altering the contents of a window the 
blinkers all go away. The way this works is that before characters are output or 
graphics are drawn, the blinker gets turned off; it comes back later. This is called 
opening the blinker. You can see this happening with the mouse blinker when you 
type at a Lisp Machine. To make this work, blinkers are always drawn using 
exclusive ORing. See the variable tv:alu-xor, page 119. 

Every blinker is associated with a particular window. A blinker cannot leave the 
area described by its window; its position is expressed relative to the window. When 
characters are output or graphics are drawn on a window, only the blinkers of that 
window and its ancestors are opened (since blinkers of other windows cannot possibly 
be occupying screen space that might overlap this output or graphics). The mouse 
blinker is free to move all over whatever screen it is on; it is therefore associated 
with the screen itself, and so must be opened whenever anything is drawn on any 
window of the screen. 

The window system provides a few kinds of blinkers. Blinkers are implemented as 
instances of flavors, too, and have their own set of messages that they understand, 
which is distinct from the set that windows understand. 

Positions of blinkers are always expressed in pixels, relative to the inside of the 
window (that is, the part of the window that doesn't include the margins). 

12.8.1 General Blinker Operations 

tv:make-blinker window feoptional (flavor Function 

'tvtrectangular-blinkerj &rest options 
Create and return a new blinker. The new blinker is associated with the 
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given window, and is of the given flavor. Other useful flavors of blinker are 
documented below. The options are initialization-options to the blinker flavor. 
All blinkers include the tv:blinker flavor, and so init options taken by 
tvrblinker will work for any flavor of blinker. Other init options may only 
work for particular flavors. 

:x-pos x (for tvrblinker) Init Option 

Along with the :y-pos init option, set the initial position of the blinker within 
the window. This init option is irrelevant for blinkers that follow the cursor. 
The initial position for nonfollowing blinkers defaults to the current cursor 
position. 

:y-pos y (for tvrblinker) Init Option 

Along with the rx-pos init option, set the initial position of the blinker within 
the window. This init option is irrelevant for blinkers that follow the cursor. 
The initial position for nonfollowing blinkers defaults to the current cursor 
position. 

rread-cursorpos of tvrblinker Method 

Returns two values: the x and y components of the position of the blinker 
within the inside of the window. 

:set-cursorpos x y of tvrblinker Method 

Set the position of the blinker within the inside of the window. If the 
blinker had been following the cursor, it stops doing so, and stays where you 
put it. 

:follow-p t-or-nil (for tvrblinker) Init Option 

Set whether the blinker follows the cursor; if this option is non-nil, it does. 
By default, this is nil, and so the blinker's position gets set explicitly. 

:set-follow-p new-follow-p of tvrblinker Method 

Set whether the blinker follows the cursor. If this is nil, the blinker stops 
following the cursor and stays where it is until explicitly moved. Otherwise, 
the blinker starts following the cursor. 

rvisibility symbol (for tvrblinker) Init Option 

Set the initial visibility of the blinker. This defaults to rblink. 

:set-visibility new-visibility of tvrblinker Method 

Set the visibility of the blinker, new-visibility should be one of ron, nil, roff, 
t, or rblink. For the meaning of these values: See the section "Blinkers", 
page 146. 

tdeselected-visibility symbol (for tvrblinker) Init Option 

Set the initial deselected visibility. By default, it is ron. 



149 
March 1985 Using the Window System 



rdeselected-visibility of tvrblinker Method 

Examine the deselected visibility of the blinker. 

:set-deselected-visibility new-visibility of tv:blinker Method 

Change the deselected visibility of the blinker. 

:half-period n-60ths (for tvrblinker) Init Option 

Set the initial value of the half-period of the blinker. This defaults to 15. 

:half-period of tvrblinker Method 

Examine the half-period of the blinker. 

rset-half-period new-half-period of tvrblinker Method 

Change the half-period of the blinker. 

rset-sheet new-window of tvrblinker Method 

Set the window associated with the blinker to be new-window. If the old 
window is an ancestor or descendant of new-window y adjust the (relative) 
position of the blinker so that it does not move. Otherwise, move it to the 
point (0,0). 

tvrsheet-following-blinker window Function 

Take a window and return a blinker that follows the window's cursor. If 
there isn't any, it returns nil. If there is more than one, it returns the first 
one it finds (it is pretty useless to have more than one, anyway). 

tvrtoirn-off-sheet-blinkers window Function 

Set the visibility of all blinkers on window to roff. 

12.8.2 Specialized Blinkers 

tvrrectangular-blinker Flavor 

This is one of the flavors of blinker provided for your use. A rectangular 
blinker is displayed as a solid rectangle; this is the kind of blinker you see in 
Lisp Listeners and Editor windows. The width and height of the rectangle 
can be controlled. 

rwidth n-pixels (for tvrrectangular-blinker) Init Option 

Set the initial width of the blinker, in pixels. By default, it is set to the 
font-blinker-width of the zeroth font of the window associated with the 
blinker. 

rheigbt n-pixels (for tvrrectangular-blinker) Init Option 

Set the initial height of the blinker, in pixels. By default, it is set to the 
font-blinker-height of the zeroth font of the window associated with the 
blinker. 
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:set-size new-width new-height of tv:rectangular-blinker Method 

Set the width and height of the blinker, in pixels, 

tv:hollow-rectangular-blinker Flavor 

This flavor of blinker displays as a hollow rectangle; the editor uses such 
blinkers to show you which character the mouse is pointing at. This flavor 
includes tvrrectangular-blinker, and so all of tvrrectangular-blinker's init 
options and messages work on this too. 

tv:box-blinker Flavor 

This flavor of blinker is like tv:hollow-rectangular-blinker except that it 
draws a box two pixels thick, whereas the tvrhollow-rectangular-blinker 
draws a box one pixel thick. This flavor includes tvrrectangular-blinker, 
and so all of tv:rectangular-blinker's init options and messages work on 
this too. 

tv:ibeam-blinker Flavor 

This flavor of blinker displays as an I-beam (like a capital I). Its height is 
controllable. The lines are two pixels wide, and the two horizontal lines are 
nine pixels wide. 

rheight n-pixels (for tv:ibeam-blinker) Init Option 

Set the initial height of the blinker. It defaults to the line-height of the 
window. 

tvtcharacter-blinker Flavor 

This flavor of blinker draws itself as a character from a font. You can 
control which font and which character within the font it uses. 

:font font (for tvxharacter-blinker) Init Option 

Set the font in which to find the character to display. This may be anything 
acceptable to the :parse-font-descriptor message of the window's screen. 
You must provide this. 

:char ch (for tvrcharacter-blinker) Init Option 

Set the character of the font to display. You must provide this. 

:set-character new-character &optional new-font of Method 

tv:character-blinker 

Set the character to be displayed to new-character. Also, if new-font is 
provided, set the font to new-font, new-font may be anything acceptable to 
the :parse-font-descriptor message of the window's screen. 
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12.9 Mouse Input 

12.9.1 Handling the Mouse 

Along with the keyboard, the mouse can be used by any program as an input device. 
The functions, variables, and flavors described below allow you to use the mouse to 
do some simple things. To get advanced mouse behavior in your own programs, like 
the way the editor gets the mouse to put a box around the character being pointed 
at, you have to extend the window system by writing your own methods, which is 
beyond the scope of this manual. Of course, you can invoke the built-in choice 
facilities, such as menus and multiple-choice windows and so on; these high-level 
facilities are described elsewhere: See the section "Window System Choice Facilities", 
page 201. 

The window system includes a process called Mouse that normally tracks the mouse. 
To track the mouse means to examine the hardware mouse interface, noting how 
the mouse is moving, and adjust Lisp variables and the mouse blinker to follow the 
position being indicated by the user. The mouse process also keeps track of which 
window owns the mouse at any time. For example, when the mouse enters an 
Editor window, the editor window becomes the owner, and to indicate this, the 
blinker changes to a northeast arrow instead of a northwest arrow; this is all done 
by the mouse process. 

In general, the window that owns the mouse is the window that is under the 
mouse; but since the windows are arranged in a hierarchy, generally a window, its 
superior, its superior's superior, and so on, are all under the mouse at the same 
time. So the window that owns the mouse is really the lowest window in the 
hierarchy (farthest in the hierarchy from the screen) that is visible (it and all its 
ancestors are exposed). If you move the window to part of the screen occupied by a 
partially visible window, then one of its ancestors (often the screen itself) becomes 
the owner. The screen handles single-clicking on the left button by selecting the 
window under it; this is why you can select partially visible windows with the mouse. 

In general, the mouse process decides how to handle the mouse based on the flavor 
of the window that owns the mouse. Some flavors handle the mouse themselves, 
running in the mouse process, in order to be able to put little boxes and such 
around things, usually to indicate what would happen if you were to click a button. 
The Editor, the Inspector, menus, and other system facilities do this. For you to do 
it yourself, you must extend the window system, creating your own methods to be 
run in the mouse process; that is beyond the scope of this document. The flavor of 
the window owning the mouse is also what usually controls the effect of clicking the 
mouse buttons. 

There are three ways for you to use the mouse without writing your own methods. 
First, you can mix in flavors to your window to tell the mouse process to let you 
know when the mouse is clicked. Secondly, you can watch the mouse moving and 
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watch the buttons, letting the mouse process do the tracking. Finally, you can turn 
off the mouse process and do your own tracking. You have to choose one of these 
three ways to use the mouse; you can't mix them. Note that you can also use 
various high-level facilities to get certain specific mouse behavior: You can create 
windows with mouse-sensitive items (like the List Buffers (m-x) command in the 
Editor), menus, multiple-choice windows, and more. 

tv:mouse-sheet Variable 

The superior window, usually the main screen, that contains the position of 
the mouse. 

ihandle-mouse of tv:essential-mouse Method 

The mouse overseer sends this message when the mouse enters the window. 
The method calls the default mouse handler, which returns when the mouse 
moves outside the window. 

:mouse-moves x y of tv:essential-mouse Method 

The default mouse handler sends this message to the window when the 
mouse has moved or buttons have been pushed, x and v represent the 
current position of the mouse if it has moved or its position at the time of 
the click if buttons have been pushed. The arguments are in the window's 
outside coordinate system. The method tracks the mouse blinker. 

:who-line-documentation-string of tvrsheet Method 

The Scheduler periodically sends this message to the window owning the 
mouse. The returned value is displayed in the mouse documentation line. 
The value should be a string or, for no documentation, nil. This method 
returns nil; supply your own to provide mouse documentation. 

tv:mouse-set-blinker-cursorpos Function 

Positions the mouse blinker at point (tv:mouse-x, tv:mouse-y) on 
tv:mouse-sheet. 

tvrmouse-wakeup Function 

Causes tv:mouse-input to return as if the mouse had moved. This causes 
the default mouse handler to send the window owning the mouse a 
:mouse-moves message. 

12.9.2 Mouse Clicks 

Clicks on the mouse are sometimes encoded into an integer. Such integers are 
normally forced into I/O buffers of windows and so they are distinguished from 
regular keyboard characters by having the %%kbd-mouse bit turned on. If this bit 
is set in an integer in an I/O buffer, it is interpreted as a mouse click. The 
%%kbd-mouse-button field tells you which button was clicked; 0, 1, and 2 mean 
the left, middle, and right buttons, respectively. The value in the 
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%%kbd-mouse-n-clicks field is one less than the number of times the mouse was 
clicked. These characters can be typed in symbolically as #\mouse-6-rc, where b is a 
letter for which button (1, m, or r) and n is one greater than the 
%%kbd-mouse-n-clicks field. For example, #\mouse-r-2 means a double-click on 
the right-hand button. 

One way to use the mouse is to get mouse clicks sent to your I/O buffer. This is 
the easiest thing to do, though it is insufficient if your application requires that you 
know more than just when the mouse is clicked. Blips representing mouse clicks are 
sent by the :mouse-click method of tv:essential-mouse, a component of 
tv:minimum-window. You can receive mouse blips, along with other characters, by 
sending the window an :any-tyi message. 

:mouse-click buttons x y of tv:essentiaI-mouse Method 

This method is called by the :mouse-buttons method of 
tv:essential-mouse, which is called by the default mouse handler when 
mouse buttons are pushed, buttons is an encoded integer representing the 
buttons pushed; use reader macros like #\mouse-r-l to handle these integers 
in yoUr program, x and y represent the position of the mouse at the time of 
the click, in the window's outside coordinates. 

If the click is #\mouse-r-2, the :mouse-buttons method pops up a system 
menu. Otherwise, if the window has an I/O buffer, :mouse-click sends it a 
blip of the form (:mouse-button buttons window x y). In addition, if the 
click is #\mouse-l-l, the window is selected. 

:mouse-click methods are combined using :or combination, so the 
:mouse-click method of tv:essential-mouse runs only if no earlier method 
handles the message (and all earlier methods return nil). 

The following example illustrates the use of the :any-tyi message to receive both 
mouse and keyboard input to windows. It is a simple drawing program whose 
command loop accepts single keystroke or mouse click commands. This program does 
not require any special flavor of window in order to run. It runs using any window 
that can become the value of terminal-io. 

(defun draw-help () 
(send terminal-io ': clear-window) 
(format t "Click the left mouse button to draw a square. ~@ 

Click the middle mouse button to draw a circle. ~@ 

Click the right mouse button to draw a triangle. ~@ 

Type REFRESH to clear the screen. ~@ 

Type END to exit.~@ 

Type HELP for documentation.-^")) 
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(defun draw ( ) 
(draw-help) 

(loop for command = (send terminal-io *:any-tyi) 
do (cond ((fixp command) 

(selectq command 
(Arefresh (send terminal-io *: clear-window)) 
(#\end (return)) 
(Ahelp (draw-help)) 
(t (beep)))) 
((eq (car command) * :mouse-button) 
(destructuring-bind (click nil x y) (cdr command) 
(selectq click 

(#\mouse-l-1 (send terminal-io ': draw-rectangle 20 20 x y)) 
(#\mouse-m-1 (send terminal-io 'rdraw-circle x y 10)) 
(#\mouse-r-1 (send terminal-io ': draw- triangle 

x y (- x 10) (+ y 20) (+ x 10) (+ y 20))) 
(t (beep))))) 
(t (beep))))) 

The following subtle point might explain some difficulties you might have with this 
method. The characters (or blips) created by the method go straight into the 
window's I/O buffer. Under some circumstances they can bypass pending characters 
that have been typed ahead at the keyboard. So if you type something and then 
click at something in rapid succession while your program is busy, the program 
might see the click before it sees the character from the keyboard. 

12.9.3 Grabbing the Mouse 

When the mouse is grabbed, the mouse process gets told that no window owns the 
mouse, and it changes the mouse blinker back to the default (a northeast arrow). 
The mouse process continues to track the mouse, and your process can now watch 
the position and the buttons by using the variables and functions described below. 

tv:with-mouse-grabbed Special Form 

A tv:with-mouse-grabbed special form just has a body: 

(tv:with-mouse-grabbed 
forml 
form2) 

The forms inside are evaluated with the mouse grabbed. 

tv:with-mouse-grabbed-on-sheet (&optional (sheet 'self)) &body Special Form 
body 
Evaluates body with the mouse grabbed and confined to sheet. During 
execution the variables tv:mouse-x and tv:mouse-y are relative to the 
window's outside coordinates. The default value of sheet is self, so if sheet is 
not supplied, this form needs to appear inside a method or defun-method of a 
window flavor. 



155 
March 1985 Using the Window System 



tv:with-mouse-and-buttons-grabbed &body body Special Form 

The forms in body are evaluated with the mouse and buttons grabbed. 
When the buttons are grabbed, the mouse process does not maintain the 
value of tv:mouse-last-buttons. Instead, the user process can read directly 
from the mouse buttons, without losing clicks that the mouse process might 
fail to notice. Within the body of this form, you can call the functions 
tv:mouse-wait, tv:wait-for-mouse-button-down, 
tv:wait-for-mouse-button-up, and tv:mouse-buttons. 

tv:with-mouse-and-buttons-grabbed-on-sheet (&optional (sheet Special Form 

'self)) &body body 
Like tv:with-mouse-and-buttons-grabbed, except that the mouse is 
confined to sheet. During execution the variables tv:mouse-x and 
tv:mouse-y are relative to the window's outside coordinates. The default 
value of sheet is self, so if sheet is not supplied, this form needs to appear 
inside a method or defun-method of a window flavor. 

tv:mouse-x Variable 

The value is the x-coordinate of the position of the mouse, in pixels, 
measured from the upper-left corner of the screen the mouse is on (the value 
of tv:mouse-sheet). This variable is maintained by the process handling the 
mouse, normally the mouse process. It is in outside coordinates, since the 
mouse might be in the margins somewhere. 

tv:mouse-y Variable 

The value is the y-coordinate of the position of the mouse, in pixels, 
measured from the upper-left corner of the screen the mouse is on (the value 
of tv:mouse-sheet). This variable is maintained by the process handling the 
mouse, normally the mouse process. It is in outside coordinates, since the 
mouse might be in the margins somewhere. 

tv:mouse-last-buttons Variable 

This variable contains the last setting of the mouse pushbuttons noticed by 
the process handling the mouse, which is normally the mouse process. The 
numbers 1, 2, and 4 represent the left, middle, and right buttons 
respectively, and the value of tv:mouse-last-buttons is the sum of the 
numbers representing the buttons that were being held down. 

tv:mouse-wait &optional (old-x tv:mouse-x) (old-y tv:mouse-y) Function 

(old-buttons tv:mouse-last-buttons) (whostate 
'Mouse ") (timeout nil) 
This function waits until any of the variables tv:mouse-x, tv:mouse-y, or 
tv:mouse-last-buttons to become different from the values passed as 
arguments, or until timeout sixtieths of a second have elapsed. While 
waiting, whostate is displayed in the status line. To avoid timing errors, your 
program should examine the values of the variables, use them, and then pass 
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in the values that it examined as arguments to tv:mouse-wait when it is 
done using the values and wants to wait for them to change again. It is 
important to do things in this order, or else you might fail to wake up if one 
of the variables changed while you were using the old values and before you 
called tv:mouse-wait. 

tv:mouse-wait returns three values: 

• An integer representing the state of the mouse buttons, in the format 
used by the variable tv:mouse-last-buttons 

• The X-coordinate of the mouse 

• The Y-coordinate of the mouse 

tv:wait-for-mouse-button-down &optional (prompt Uutton") Function 

If any buttons are down, waits until all the buttons are up, then waits for 
any mouse button to be pushed. If no buttons are down, waits for any 
button to be pushed, prompt is the whostate to display while waiting. 
Returns the same three values as tv:mouse-wait. 

This must be called inside a tv:with-mouse-and-buttons-grabbed or a 
tv:with-mouse-and-buttons-grabbed-on-sheet form. 

tv:wait-for-mouse-button-up &optional (prompt 'Release Button ") Function 

(timeout nil) 
Waits until all mouse buttons are up, or until timeout sixtieths of a second 
have elapsed, prompt is the whostate to display while waiting. Returns the 
same three values as tv:mouse-wait. 

This must be called inside a tv:with-mouse-and-buttons-grabbed or a 
tv:with-mouse-and-buttons-grabbed-on-sheet form. 

tv:mouse-button-encode bd Function 

When a mouse button has been pushed, and you want to interpret this push 
as a click, call this function. It watches the mouse button and figures out 
whether a single-click or double-click is happening. It returns nil if no 
button is pushed, or an encoded integer giving the click in the usual way. 

You only call tv:mouse-button-encode when a button has just been pushed; 
that is, when you see some button down that was not down before. You 
have to pass in the argument, bd, which is a bit mask saying which buttons 
were pressed down: which are down now that were not down "before". The 
form (boole 2 old-buttons new-buttons) computes this mask. 

tv:who-line-mouse-grabbed-documentation Variable 

When grabbing or usurping the mouse, you should explain what is going on 
in the mouse documentation line at the bottom of the screen. 
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tv:with-mouse-grabbed and tv:with-mouse-usurped bind this variable to 
nil, which makes the mouse documentation line blank. Inside the body of 
one of these special forms, you can setq this variable to a string to be 
displayed in the mouse documentation line. If your program has "modes" 
that affect how the click acts, each part of the program should setq this 
variable to its own documentation. 

12.9.4 Usurping the Mouse 

You can tell the mouse process not to do anything, and track the mouse in your 
own process. This is called usurping the mouse. The mouse blinker disappears, and 
if you want any visual indication of the mouse to appear, you have to do it yourself. 

tv:with-mouse-usurped Special Form 

A tv:with-mouse-usurped special form just has a body: 

(tv:with-mouse-usurped 
forml 
form2) 

The forms inside are evaluated with the mouse usurped. 

tv:mouse-input &optional (wait-flag t) Function 

Wait until something happens with the mouse, and then return saying what 
happened. Six values are returned. The first two are delta-x and delta-y, 
which are the distance that the mouse has moved since the last time 
tv.mouse-input was called. The second two are buttons-newly-pushed and 
buttons-newly-raised , which are bit masks (using the bit assignment used by 
tv:mouse-last-buttons) saying what buttons have changed since the last 
time tv:mouse-input was called. The last two values are the current x- and 
y-position of the mouse or, if any buttons changed, the position of the mouse 
at that time. 

You can only call this function with the mouse usurped; otherwise you will 
get in the way of the mouse process, which calls it itself, and mouse tracking 
will not work correctly. 

The variables tv:mouse-x and tv:mouse-y are not maintained by this 
function; you must do it yourself if you want to keep track of a cumulative 
mouse position. tv:mouse-last-buttons is maintained. 

The buttons-newly-pushed value is suitable for being passed as an argument 
to tv:mouse-buttons-encode, which can be used with the mouse usurped as 
well as with the mouse grabbed. 

If wait-flag is nil, then the function does not wait; it can return with all 
zeroes, indicating that nothing has changed. 
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tv:mouse-buttons &optional peek Function 

Return the current state of the mouse buttons. This function has no state 
or anything; it just goes straight to the hardware and reads the current 
state. If peek is not nil, it looks at the state without pulling anything out of 
the buffer. 

tv:mouse-buttons returns four values: 

• An integer representing the state of the mouse buttons, in the format 
used by the variable tv:mouse-last-buttons 

• An integer representing the time when that state was true 

• The X-coordinate of the mouse at that time 

• The Y-coordinate of the mouse at that time 

To use some parts of the mouse software, such as tv:mouse-button-encode, 
you can store these four returned values into the variables 
tv:mouse-last-buttons, tv:mouse-last-buttons-time, 
tv:mouse-last-buttons-x, and tv:mouse-last-buttons-y, respectively. The 
mouse process does this itself when the mouse is not usurped. 

12.9.5 Controlling the Mouse Outside a Window 

tv:hysteretic-window-mixin Flavor 

By mixing this flavor into your window, you control the mouse for a small 
area outside the window as well as the area inside the window. You can 
control the hysteresis, which is the number of pixels away from the window 
that the mouse has to get before this window ceases to own it. This mixin 
is used by momentary menus, so that if you accidentally slip a bit outside the 
menu, the menu won't vanish; you have to get well away from it before it 
vanishes. 

rhysteresis n-pixels (for tv:hysteretic-window-mixin) Init Option 

Set the initial value of the hysteresis, in pixels. It defaults to 25. (decimal). 

rhysteresis of tv:hysteretic-window-mixin Method 

Examine the hysteresis of the window, in pixels. 

:set-hysteresis new-hysteresis of tvrhysteretic-wmdow-mixin Method 

Set the hysteresis of the window, in pixels. 
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12.9.6 Scaling Mouse Motion 

tv:mouse-x-scale-array Variable 

The value of this variable is an array that, along with the array that is the 
value of tv:mouse-y-scale-array, can be used to control mouse scaling. 
These arrays determine the relation between the rates of motion of the 
mouse on the table and the mouse cursor on the screen. This relation can 
be nonlinear and can vary with the speed of the mouse. For example, fast 
mouse motion can move the cursor a distance that is proportionally greater 
than slow mouse motion. 

Scaling is computed as follows. The even-numbered elements of 
tv:mouse-x-scale-array are compared with the value of tv:mouse-x-speed, 
and the even-numbered elements of tv:mouse-y-scale-array are compared 
with the value of tv:mouse-y-speed. tv:mouse-x-speed and 
tv:mouse-y-speed are the x- and y-components of the mouse speed on the 
table, typically in units of hundredths of an inch per second. 

For each array, the first even array element that is greater than the mouse 
speed causes its corresponding odd-numbered array element to be multiplied 
by the mouse motion on the table and then divided by 1024 (decimal). The 
result is the mouse motion on the screen. Appropriate care is taken to save 
the fractions for the next computation. 

The default array setup code is as follows: 

;;; Use a scale of 2/3 in X, 3/5 in Y when moving at slow speed, 

;;; double that at high speed 

(aset 80. tv:mouse-x-scale-array 0) 

(aset (// (lsh 2 10.) 3) tv:mouse-x-scale-array 1) 

(aset 80. tv:mouse-y-scale-array 0) 

(aset (// (lsh 3 10.) 5) tv:mouse-y-scale-array 1) 

(aset #017777777777 tv:mouse-x-scale-array 2) 

(aset (// (lsh 4 10.) 3) tv:mouse-x-scale-array 3) 

(aset #017777777777 tv:mouse-y-scale-array 2) 

(aset (// (lsh 6 10.) 5) tv:mouse-y-scale-array 3)) 

The following code provides for simple scaling of motion for the Hawley 
mouse. The microcode knows specially about each array. You can store into 
each array, but you cannot replace it with a new array or use 
adjust-array-size on it. 
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Aids to trying speed-dependent scaling 
Specs are scale- factor speed-break 
No attempt to treat X and Y differently 

Args of (1 80. 2) seem to be about right for the Hawley mouse 
(defun mouse-speed-hack (&rest specs) 
(loop for (scale speed) on specs by 'cddr 
for i from by 2 

do (aset (or speed #037777777) tv:mouse-x-scale-array i) 
(aset (or speed #037777777) tv:mouse-y-scale-array i) 
(aset (// (fix (* 2 scale 1024.)) 3) 
tv:mouse-x-scale-array (1+ i)) 
(aset (// (fix (* 3 scale 1024.)) 5) 
tv:mouse-y-scale-array (1+ i)))) 

(defun hawley-mouse-hack () 
(mouse-speed-hack 1 80. 2)) 

tv:mouse-y-scale-array Variable 

The value of this variable is an array that, along with the array that is the 
value of tv:mouse-x-scale-array, can be used to control mouse scaling. See 
the variable tv:mouse-x-scale-array, page 159. 



12.10 The Keyboard 

Another way of using the keyboard, different from reading a stream of input 
characters from a window, is to treat it as a "random access" device and look at the 
instantaneous state of particular keys. 

One application for checking the state of keys is in user interfaces where the action 
of mouse clicks is modified by the shift keys on the keyboard; you can have one 
hand on the mouse and the other on the keyboard. You can use the variables 
tv:mouse-double-click-time and tv:*mouse-incrementing-keystates* to augment 
or replace double clicks with shifted clicks. 

Mouse characters — characters with the %%kbd-mouse bit set to 1 — can be 
modified with the modifier keys control, meta, super, and hyper, just as keyboard 
characters can. Which of these keys modify mouse characters depends on the value 
of the variable tv:*mouse-modiiying-keystates*. 

The editor considers each modified mouse click to be a separate command. You can 
bind commands to particular modified mouse clicks. You can also use Install Mouse 
Macro (n-x) with modified mouse clicks to increase the number of mouse macros 
available. 

You can use login-forms in an init file to set the variables 
tv:mouse-double-click-time, tv:*mouse-incrementing-keystates*, and 
tv:*mouse-modifymg-keystates* and customize the behavior of the mouse. 
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tv:key-state key-name Function 

Returns t if the keyboard key named key-name is currently depressed, nil if 
it is not. 

key-name may be the symbolic name of a modifier key, from the table below, 
or the number of a nonmodifier key, which is the character you get when 
you type that key without any modifiers: a lowercase letter, a digit, or a 
special character. Modifier keys that come in pairs have three symbolic 
names; one for the left-hand key, one for the right-hand key, and one for 
both, which is considered to be depressed if either member of the pair is. 



The modifier key names are: 




:shift 


left-shift 


:right-shift 


: symbol 


left-symbol 


rright-symbol 


: control 


left-control 


:right-control 


:meta 


left-meta 


:right-meta 


:super 


left-super 


:right-super 


: hyper 


left-hyper 


: right-hyper 


: caps- lock 


repeat 


: mode-lock 



tv:mouse-double-click-time Variable 

The maximum period of time (in microseconds) between mouse clicks for 
which the clicks are interpreted as a double click instead of two single clicks. 
Default: 200000 (decimal). If you set this to nil, disabling double clicking 
entirely, mouse response time improves slightly. 

tv:*mouse-incrementing-keystates* Variable 

A list of names of keys, acceptable to tv:key-state. If one or more of these 
keys are pressed, single mouse clicks are interpreted as double clicks. 
Default: Oshift). 

tv:*mouse-modifying-keystates* Variable 

A list of names of keys, acceptable to tv:key-state. If one or more of these 
keys are pressed, sets the corresponding modifier bits in the mouse character. 
Default: (:control :meta :super rhyper). If a key appears as an element 
of both this list and the list that is the value of 

tv:*mouse-incrementing-keystates*, the modifier bit is set and the click is 
interpreted as a double click. 

tv:key-test Function 

tv:key-test allows you to check that your keyboard and mouse hardware are 
functioning correctly. It displays a keyboard image and a mouse image. The 
mouse image tracks the mouse when mouse tracking is functioning correctly. 
Holding down a key or button causes the corresponding key or button on the 
screen to go into inverse video. The END key returns. This function is not 
loaded as part of the world load but is available: 
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(load "sys:window;keytest") 
(tv: key- test) 



12.11 Window Sizes and Positions 

The messages and init options in this section are used to examine and set the sizes 
and positions of windows. There are many different messages, that let you express 
things in different forms that are convenient in varying applications. Usually, sizes 
are in units of pixels. However, sometimes we refer to widths in units of characters 
and heights in units of lines. The number of horizontal pixels in one character is 
called the character-width, and the number of vertical pixels in one line is called the 
line-height. See the section "Character Output to Windows", page 108. 

As has been mentioned before, a window has two parts: the inside and the margins. 
The margins include borders, labels, and other things; the inside is used for drawing 
characters and graphics. Some of the messages below deal with the outside size 
(including the margins) and some deal with the inside size. 

Since a window's size and position are usually established when the window is 
created, we will begin by discussing the init options that let you specify the size and . 
position of a new window. To make things as convenient as possible, there are 
many ways to express what you want. The idea is that you specify various things, 
and the window figures out whatever you leave unspecified. For example, you can 
specify the right-hand edge and the width, and the position of the left-hand edge 
will automatically be figured out. If you underspecify some parameters, defaults are 
used. Each edge defaults to being the same as the corresponding inside edge of the 
superior window; so, for example, if you specify the position of the left edge, but 
don't specify the width or the position of the right edge, then the right edge will 
line up with the inside right edge of the superior. If you specify the width but 
neither edge position, the left edge will line up with the inside left edge of the 
superior; the same goes for the height and the top edge. 

In order for a window to be exposed, its position and size must be such that it fits 
within the inside of the superior window. If a window is not exposed, then there 
are no constraints on its position and size; it may overlap its superior's margins, or 
even be outside the superior window altogether. 

All positions are specified in pixels and are relative to the outside of the superior 
window. 

The following options set various position and size parameters. The size and position 
of the window are computed from the parameters provided by these and other 
options, and the set of defaults described above. Note that all edge parameters are 
relative to the outside of the superior window. 
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12.11.1 Initializing Window Size and Position 

:left left-edge (for tvrsheet) 

Specifies the x-coordinate of the left edge of the window. 

:x left-edge (for tv:sheet) 

Specifies the x-coordinate of the left edge of the window. 

:top top-edge (for tv:sheet) 

Specifies the y-coordinate of the top edge of the window. 

:y top-edge (for tvrsheet) 

Specifies the y-coordinate of the top edge of the window. 



Init Option 

Init Option 

Init Option 

Init Option 
ge of the window. 

rposition (left-edge top-edge) (for tv:sheet) Init Option 

Specifies the x-coordinate of the left edge and the y-coordinate of the top 
edge of the window. 

rright right-edge (for tv.sheet) Init Option 

Specifies the x-coordinate of the right edge of the window. 

rbottom bottom-edge (for tvrsheet) Init Option 

Specifies the y-coordinate of the bottom edge of the window. 

rwidth outside-width (for tv:sheet) Init Option 

Specifies the outside width of the window. 

rheight outside-height (for tvrsheet) Init Option 

Specifies the outside height of the window. 

rsize (outside-width outside-height) (for tvrsheet) Init Option 

Specifies the outside width and height of the window. 

rinside-width inside-width (for tvrsheet) Init Option 

Specifies the inside width of the window. 

rinside-height inside-height (for tvrsheet) Init Option 

Specifies the inside height of the window. 

rinside-size (inside-width inside-height) (for tvrsheet) Init Option 

Specifies the inside width and height of the window. 

redges (left-edge top-edge right-edge bottom-edge) (for tvrsheet) Init Option 

Specifies the x-coordinates of the left and right edges and the y-coordinates of 
the top and bottom edges of the window. 



164 

Programming the User Interface March 1985 



:character-width spec (for tvrsheet) Init Option 

This is another way of specifying the width, spec is either a number of 
characters or a character string. The inside width of the window is made to 
be wide enough to display those characters, or that many characters, in font 
zero. 

rcharacter-height spec (for tv:sheet) Init Option 

This is another way of specifying the height, spec is either a number of lines 
or a character string containing a certain number of lines separated by 
carriage returns. The inside height of the window is made to be that many 
lines. 

:integral-p t-or-nil (for tvrsheet) Init Option 

The default is nil. If this is specified as t, the inside dimensions of the 
window are made to be an integral number of characters wide and lines high, 
by making the bottom margin larger if necessary. 

:edges-from source (for tvressential-window) Init Option 

Specifies that the window is to take its edges (position and size) from source, 
which can be one of: 

a string 

The inside-size of the window is made large enough to display the 
string, in font zero. 

a list (left-edge top-edge right-edge bottom-edge) 

Those edges, relative to the superior, are used, exactly as if you had 
used the redges init option. 

mouse 

The user is asked to point the mouse to where the top-left and 
bottom-right corners of the window should go. (This is what happens 
when you use the [Create] command in the System menu, for 
example.) 

a window 

That window's edges are copied. 

:minimum-width n-pixels (for tvressential-window) Init Option 

In combination with the :edges-from :mouse init option, this option and 
rminimum-height specify the minimum size of the rectangle accepted from 
the user. If the user tries to specify a size smaller than one or both of these 
minima, he will be beeped at, and prompted to start over again with a new 
top-left corner. 

rminimum-height n-pixels (for tvressential-window) Init Option 

In combination with the :edges-from :mouse init option, this option and 
:minimum-width specify the minimum size of the rectangle accepted from 
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the user. If the user tries to specify a size smaller than one or both of these 
minima, he will be beeped at, and prompted to start over again with a new 
top-left corner. 

tv:set-default-window-size flavor-name superior existing-windows Function 

&rest options 
tv:set-default-window-size allows you to modify the default size chosen by 
the system when you create a window without specifying either a size or a 
position for it. For example, when you create a Lisp Listener by pressing 
SELECT c-L, the default size is the full size of the screen, unless you modify 
it. 

The arguments to tv:set-default-window-size are: 

flavor-name The flavor of window to be affected. Flavors built on top 

of this do not inherit this flavor's default window size, nil 
here means all windows. 

superior The window whose direct inferiors are to be affected; 

typically, the value of tv:main-screen. 

existing-windows An indicator as to whether existing windows must conform 
to these options. Any non-nil argument forces all existing 
windows of the specified flavor-name and superior to 
conform to the options. 

options Alternating keywords and values that are used as defaults 

in creating windows whose size or position is not specified. 
Valid keywords are :width, :left, :right, :heigfat, :top, 
and rbottom. They have the same meaning as in 
tv:make-window. 

For example: 

(tv:set-default-window-size 

'zweirzmacs- frame tv:main-screen t ' :width 1400) 

12.11.2 Messages for Window Size and Position 

The group of messages below is used to examine or change the size or position of a 
window. Many messages that change the window's size or position take an 
argument called option. The reason that this argument exists is that certain new 
sizes or positions are not valid. One reason that a size may not be valid is that it 
may be so small that there is no room for the margins; for example, if the new 
width is smaller than the sum of the sizes of the left and right margins, then the 
new width is not valid. Another reason a new setting of the edges may be invalid is 
that if the window is exposed, it is not valid to change its edges in such a way that 
it is not enclosed inside its superior. In all of the messages that take the option 
argument, option may be either nil or rverify. If it is nil, that means that you 
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really want to set the edges, and if the new edges are not valid, an error should be 
signalled. If it is tverify, that means that you only want to check whether the new 
edges are valid or not, and you don't really want to change the edges. If the edges 
are valid, the message will return t; otherwise it will return two values: nil and a 
string explaining what is wrong with the edges. (Note that it is valid to set the 
edges of a deexposed inferior window in such a way that the inferior is not enclosed 
inside the superior; you just can't expose it until the situation is remedied. This 
makes it more convenient to change the edges of a window and all of its inferiors 
sequentially; you don't have to be careful about what order you do it in.) 

:change-of-size-or-margins &rest options of tvrsheet Method 

Changes window size or margins, processing options. This message is sent by 
the system; you might need to provide an rafter daemon for it. 

:size of tv:sheet Method 

Return two values: the outside width and outside height. 

:set-size new-width new-height &optional option of Method 

tv:essential-set-edges 

Set the outside width and outside height of the window to new-height and 
new-width, without changing the position of the upper-left corner. 

dnside-size of tv:sheet Method 

Return two values: the inside width and the inside height. 

:set-inside-size new-inside-width new-inside-height &optional Method 

option of tv:essential-set-edges 

Set the inside width and inside height of the window to new-inside-height 
and new-inside-width, without changing the position of the upper-left corner. 

:size-in-characters of tvrsheet Method 

Return two values: the inside size in characters, and the inside height in 
lines. 

:set-size-in-characters width-spec height-spec &optional option of Method 

tv:sheet 
Set the inside size of the window, according to the two specifications, without 
changing the position of the upper-left corner, width-spec and height-spec are 
interpreted the same way as arguments to the :character-width and 
rcharacter-height init options, respectively. 

rposition of tvrsheet Method 

Return two values: the x and y positions of the upper-left corner of the 
window, in pixels, relative to the superior window, respectively. 
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:set-position new-x new-y &optional option of Method 

tv:essential-set-edges 

Set the x and y position of the upper-left corner of the window, in pixels, 
relative to the superior window, respectively. 

redges of tv:sheet Method 

Return four values: the left, top, right, and bottom edges, in pixels, relative 
to the superior window, respectively. 

:set-edges new-left new-top new-right new-bottom &optional Method 

option of tv:essential-set-edges 
Set the edges of the window to new-left, new-top, new-right, and new-bottom, 
in pixels, relative to the superior window, respectively. 

:margins of tv:sheet Method 

Return four values: the sizes of the left, top, right, and bottom margins, 
respectively. 

:left-margin-size of tvtshest Method 

Returns the left margin size of the window in pixels. 

: top-margin-size of tvrsheet Method 

Returns the top margin size of the window in pixels. 

:right-margin-size of tv:sheet Method 

Returns the right margin size of the window in pixels. 

:bottom-margin-size oftv:sheet Method 

Returns the bottom margin size of the window in pixels. 

:inside-edges of tvrsheet Method 

Return four values: the left, top, right, and bottom inside edges, in pixels, 
relative to the top-left corner of this window. This can be useful for clipping. 
Note that this message is not analogous to the tedges message, which 
returns the outside edges relative to the superior window. 

:center-around x y of tv:essential-set-edges Method 

Without changing the size of the window, position the window so that its 
center is as close to the point (x,y), in pixels, relative to the superior window, 
as is possible without hanging off an edge. 

:expose-near mode &optional (warp-mouse-p t) of Method 

tv:essential-set-edges 

If the window is not exposed, change its position according to mode and 
expose it (with the rexpose message). If it is already exposed, do nothing. 

mode should be a list; it may be any of the following: 
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Opoint x v) 

Position the window so that its center is as close to the point fay), in 
pixels, relative to the superior window, as is possible without hanging 
off an edge of the superior. 

(:mouse) 

This is like the rpoint mode above, but the x and y come from the 
current mouse position instead of the caller. This is like what pop-up 
windows do. In addition, if warp-mouse-p is non-nil, the mouse is 
warped to the center of the window. (The mouse only moves if the 
window is near an edge of its superior; otherwise the mouse is already 
at the center of the window.) 

(rrectangle left top right bottom) 

The four arguments specify a rectangle, in pixels, relative to the 
superior window. The window is positioned somewhere next to but 
not overlapping the rectangle. In addition, if warp-mouse-p is non-nil, 
the mouse is warped to the center of the window. 

Owindow window-1 window-2 window-3 ...) 

Position the window somewhere next to but not overlapping the 
rectangle that is the bounding box of all the window-ns. You must 
provide at least one window. Usually you only give one, and this 
means that the window is positioned touching one edge of that 
window. In addition, if warp-mouse-p is non-nil, the mouse is warped 
to the center of the window. 



12.12 Window Margins, Borders, and Labels 

There is a distinction between the inside and outside parts of the window. The part 
of the window that is not the inside part is called the margins. There are four 
margins, one for each edge. The margins sometimes contain a border, which is a 
rectangular box drawn around the outside of the window. Borders help the user see 
what part of the screen is occupied by which window. The margins also sometimes 
contain a label, which is a text string. Labels help the user see what a window is 
for. 

A label can be inside the borders or outside the borders (usually it is inside). In 
general, there can be lots of things in the margins; each one is called a margin item. 
Borders and labels are two kinds of margin items. In any flavor of window, one of 
the margin items is the innermost; it is right next to the inside part of the window. 
Each successive margin item is outside the previous one; the last one is just inside 
the edges of the window. Each margin item is created by a flavor's being mixed in. 
You can control which margin items your window has by which flavors you mix in, 
and you can control their order by the order in which you mix in the flavors. 
Margin item flavors closer to the front of the component flavor list are further 
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outside in the margins. The tv:window flavor has as components 
tv:borders-mhrin and tv:label-mixin, in that order, and so the label is inside the 
border. 

This section lists the margin item flavors that you can mix in, and explains some 
messages and init options that you can use to control what the margin items do. 

You can ask for the size of the margins with the :margins message. 

tv:margin-space-mixin Flavor 

This flavor provides a margin item that just leaves some blank space. It 
might be useful if you're using scroll bars, and you want to leave a little 
white space between the scroll bar and the inside of the window. 

:space (for tv:margin-space-mixin) Init Option 

Initializes the amount of blank space in the margins of the window. Possible 
values: 

nil No space 

t One pixel blank in each of the four margins 

n n pixels of space in each of the four margins (n is an 

integer) 

(left top right bottom) 

left pixels blank in the left margin, top pixels blank in the 
top margin, and so on (values are integers) 

:space of tv:margin-space-mixin Method 

Returns a list of four elements, (left top right bottom). These are integers 
representing the number of pixels of blank space in the four margins of the 
window. 

:set-space new-space of tv:margin-space-mixin Method 

Specifies the amount of blank space to be left in the margins of the window. 
Possible values of new-space: 

nil No space 

t One pixel blank in each of the four margins 

n n pixels of space in each of the four margins (n is an 

integer) 

(left top right bottom) 

left pixels blank in the left margin, top pixels blank in the 
top margin, and so on (values are integers) 
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12.12.1 Window Borders 

tv:borders-mixhi Flavor 

The tv:borders-mixin margin item creates the borders around windows that 
you often see when using the Lisp Machine. You can control the thickness 
of each of the four borders separately, or of all of them together. You can 
also specify your own function to draw the borders, if you want something 
more elaborate than simple lines. 

The borders also include some white space left between the borders and the 
inside of the window. The thickness of this white space is called the border 
margin width. The space is there so that characters and graphics that are 
up against the edge of the inside of the window, or the next-innermost 
margin item, do not "merge" with the border. 

rborders argument (for tv:borders-mixin) Init Option 

This option initializes the parameters of the borders, argument may have 
any of the following values: 

nil There are no borders at all. 

a symbol or a number 

A specification which applies to each of the four borders. 

a list (left top right bottom) 

Specifications for each of the four borders of the window. 

a list (keywordl sped keyword2 spec2...) 

Specifications for the borders at the edges selected by the keywords, 
which may be among :left, :top, :right, : bottom. 

Each specification for a particular border may be one of the following. It 
specifies how thick the border is and the function to draw it. 

nil This edge should not have any border. 

t The border at this edge should be drawn by the default function with 

the default thickness. 

a number 

The border at this edge should be drawn by the default function with 
the specified thickness. 

a symbol 

The border at this edge should be drawn by the specified function 
with the default thickness for that function. 

a cons (function . thickness) 

The border at this edge should be drawn by the specified function 
with the specified thickness. 
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The default (and currently only) border function is 
tv:draw-rectangular-border. Its default width is 1. 

To define your own border function, you should create a Lisp function that 
takes six arguments: the window on which to draw the label, the "alu 
function" with which to draw it, and the left, top, right, and bottom edges of 
the area that the border should occupy. The returned value is ignored. The 
function runs inside a tv:sheet-force-access. You should place a 
tv:default-border-size property on the name of the function, whose value is 
the default thickness of the border; it will be used when a specification is a 
non-nil symbol. 

Note that setting border specifications to ask for a border width of zero is not 
the same thing as giving nil as the argument to this option, because in the 
former case the space for the border margin width is allocated, whereas in 
the latter case it is not. 

:set-borders new-borders of tv:borders-mhrin Method 

Redefine the borders, new-borders can be any of the things that can be used 
for the tborders init option. 

:border-margin-width n-pixels (for tv:borders-mixin) Init Option 

Set the width of the white space in the margins between the borders and 
the inside of the window. The default is 1. If some edge does not have any 
border (the specification for that border was nil) then that border won't have 
any border margin either, regardless of the value of this option; that is the 
difference between border specifications of and nil. 

:border-margin-width of tv:borders-mixin Method 

Return the value of the border margin width. 

:set-border-margin-width new-width of tv:borders-mixin Method 

Set the value of the border margin width. 

12.12.2 Window Labels 

tv:label-mixin Flavor 

The tv:label-mixin margin item creates the labels in the corner" of windows 
that you often see when using the Lisp Machine. You can control the text 
of the label, the font in which it is displayed, and whether it appears at the 
top of the window or the bottom. 

:name name (for tv:sheet) Init Option 

The value is the name of the window, which should be a string. All windows 
have names; note that this is an init option of tvtsheet. It is mentioned 
here because the main use of the name is as the default string for the label, 
if there is a label. 



172 

Programming the User Interface March 1985 



:name of tvrsheet Method 

Return the name of the window, which is a string. 

:label specification (for tv:label-mixin) Init Option 

Set the string displayed as the label, the font in which the label is displayed, 
and whether the label is at the top or the bottom of the window. Anything 
you don't specify will default; by default, the string is the same as the name 
of the window, the font is the default font for the screen, and the label is at 
the bottom of the window. 

specification may be any of: 

nil There is no label at all. 

t The label is given all the default characteristics. 

:top The label is put at the top of the window. 

tbottom 

The label is put at the bottom of the window. 

a string 

The text displayed in the label is this string. 

a font The label is displayed in the specified font. 

a list (keywordl argl keyword2 ...) 

The attributes corresponding to the keywords are set; the rest of the 
attributes default. Some keywords take arguments, and some do not. 
The following keywords may be given: 

:top The label is put at the top of the window. 

rbottom 

The label is put at the bottom of the window. 

:string string 

The text displayed in the label is string. 

:font font-descriptor 

The label is displayed in the specified font, font-descriptor may 
be any font descriptor. 

:label-size of tv:label-mixin Method 

Return the width and height of the area occupied by the label. 

:set-label specification of tv:label-mixin Method 

Change some attributes of the label, specification can be anything accepted 
by the :label init option. Any attribute that specification doesn't mention 
retains its old value. 
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tv:top-label-murin Flavor 

The tv:top-label-mixin margin item is just like tvrlabel-mixin except that 
the label is placed at the top of the window by default, instead of the 
bottom. 

tv:top-box-label-mixin Flavor 

The tv:top-box-label-mMn is just like tv:top-label-mixin except that in 
addition to the label in the top margin, it also draws a line below the label in 
the top margin. If you surround the label with borders, then the label will 
appear inside a box. You have probably seen windows like this appear as 
momentary menus, with a prompt at the top in a box. 

tv:changeable-name-mixin Flavor 

Mixing in this flavor defines a :set-name method, so that you can change 
the name of the window, redrawing the label if appropriate. This flavor 
includes tv:label-mixin, so one of the above kinds of label must be in the 
margins of the window. 

:set-name new-name of tv:changeable-name-mixin Method 

Set the name of the window to new-name, which should be a string. If the 
window is currently displaying the old name of the window as the label, then 
redraw the label using the new name as the text to be displayed. 

tv:delayed-redisplay-label-mixin Flavor 

This flavor adds the :delayed-set-label and :update-label messages to your 
window. You send a :delayed-set-label message to change the label in such 
a way that it will not actually be displayed until you send an :update-label 
message. This is especially useful for programs that suppress redisplay when 
there is typeahead; the user's commands may change the label several times, 
and you may want to suppress the redisplay of the changes in the label until 
there isn't any typeahead. 

:delayed-set-label specification of Method 

tv:delayed-redisplay-label-mixin 

This is like the :set-label method, except that nothing actually happens until 
an :update-label message is sent. 

:update-label of tv:delayed-redisplay-label-mixin Method 

Actually do the :set-label operation on the specification given by the most 
recent :delayed-set-label message. 
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12.13 Text Scroll Windows 

A window of flavor tv:text-scroll-window maintains an array of items. It displays 
these items in the window, one item per line. When the window is not large 
enough to display all the items, it provides a scroll bar. It also has methods for 
inserting and deleting items. 

Other flavors of text scroll window have additional features. One of the most useful 
flavors is tv:mouse-sensitive-text-scroll-window, which makes displayed items 
mouse sensitive. 

tv:text-scroll-window Flavor 

Maintains an array of items displayed in the window, one per line. Provides 
scrolling when not all items fit in the window. 

tv:mouse-sensitive-text-scroll-window Flavor 

A text scroll window with mouse-sensitive items. 

tv:text-scroll-window-empty-gray-hack Flavor 

A mixin flavor for text scroll windows. Makes the window gray when no 
items are displayed. 



12.14 Typeout Windows 

tv:window-with-typeout-mixin Flavor 

Flavor to mix into a superior window to provide an inferior typeout window. 

ttypeout-window (flavor-name . options) (for Init Option 

tv:essential-window-with-typeout-mixin) 

Provides a typeout window inferior to the window, flavor-name is the flavor 
of typeout window to create; options are options to tv:make-window. 

tv:typeout-window Flavor 

Standard flavor of typeout window. 

tv:typeout-window-with-mouse-sensitive-items Flavor 

A typeout window with tv:basic-mouse-sensitive-items mixed in. 

tvrtemporary-typeout-window Flavor 

A flavor of typeout window that saves and restores the bits of its superior. 
When tvrwith-terminal-io-on-typeout-window is used with a window that 
has this kind of typeout window over it, the program does not have to take 
any action to restore the display when the typeout window goes away. 
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tv:with-terminal-io-on-typeout-window (window wait-for-space-p) Special Form 

&body body 
Binds terminal-io to the typeout-window of window over the duration of the 
body, taking care of exposing and deexposing the typeout window, selection, 
etc. wait-for-space-p, if supplied and not nil, means that after executing the 
body the user should be prompted to type a space to get rid of the typeout 
window. Otherwise the typeout window goes away as soon as the body 
returns. All values of the body are returned. 



12.15 Scrolling Windows 

tv:basic-scroll-bar Flavor 

Flavor that provides basic scroll-bar scrolling. 

tv:margin-scroll-mixin Flavor 

Flavor that provides scrolling by clicking on margin regions. 

tv:flashy-scrolling-mixin Flavor 

Flavor that provides slow scrolling by moving the mouse through margin 
regions. 



12.16 Frames 

A frame is a window that is divided into subwindows, using the hierarchical 
structure of the window system. The subwindows are called panes. The panes are 
the inferiors of the frame, and the frame is the superior of each pane. Several 
heavily used systems programs use frames. For example, Inspector windows are 
frames. The default Inspector window has six panes: the interaction pane on top, 
the history pane and command menu pane below it, and three Inspect panes below 
that. The Window Debugger and Zmacs also use frames. In Zmacs, each new 
editor window is a pane of the Zmacs Frame. Zmail uses frames heavily. 

From these examples, you can see some of the things that frames are good for. In 
general, by using a frame as a user interface to an interactive subsystem, you get a 
convenient way to put many different things on the screen, each in its own place. 
Generally you can split up the frame into areas in which you can display text or 
graphics, areas where you can put menus or other mouse-sensitive input areas, and 
areas to interact with, in which keyboard input is echoed or otherwise acknowledged. 

If you use [Edit Screen] to change the shape of an Inspector or Window Debugger 
frame, the shapes of the panes are all changed so that the proportions come out 
looking as they are supposed to. If you play around with [Edit Screen] enough, you 
can even see the menus reformat themselves (changing their numbers of rows and 
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columns) in order to keep all of their items visible. The way all this works is that 
the positions and shapes of the panes, instead of being explicitly specified in units of 
pixels, are specified symbolically. When the window changes shape, the symbolic 
description is elaborated again in light of the new shape, and the panes are reshaped 
appropriately. 

This set of symbolic descriptions is called a set of constraints, and the kind of frame 
that implements the constraint mechanism is a flavor called 
tv:basic-constraint-frame. While there are other, more basic frame flavors, you 
cannot use them alone; you must write a new flavor that includes the more basic 
frame flavors in its components, and has new methods. Since writing new methods 
is beyond the scope of this document, we will simply explain how to use constraint 
frames. 

When you make a constraint frame, you specify the configuration of panes within 
the frame by creating list structure to represent the layout. The format of this list 
structure is called the constraint language. It lets you say things like "give this 
pane one third of the remaining room, then give that pane 17 pixels, and then divide 
what remains between these two panes, evenly." The constraint language is fairly 
complex. For full details: See the section "Specifying Panes and Constraints", page 
179. In general, a frame can have many different configurations. Each 
configuration is described in the constraint language, and each specifies one way of 
splitting up the frame. While the program is running, it can switch a frame from 
one configuration to another. Some panes may appear in more than one 
configuration, but other panes may be left out of one configuration, and may only be 
visible when the frame is switched to another configuration. For example, in Zmail, 
when you click on [Mail], the frame changes to a new configuration showing the 
Headers and Mail panes. 

12.16.1 Flavors for Panes and Frames 

To have a frame with panes, you must have a frame, which is a window, and you 
must have panes, each of which is a window. The flavor of each pane of a frame 
must have, as one of its components, the flavor tv:pane-mixiiL Some system 
facilities provide flavors for you that already have this flavor mixed in. For example, 
the flavor tv:command-menu-pane is a flavor that consists of tv:command-menu 
and tv:pane-mixin. (This is the kind of menu most often used in frames; menus 
are a higher-level facility.) In general, you can take any flavor of window that you 
might want to use in a pane, and make a new flavor suitable to actually be a pane 
simply by mixing in tv:pane-mixin. 

tv:pane-mixin Flavor 

The flavor of any window used as a pane of a frame must have 
tv:pane-mixm as one of its components. For example, the flavor 
tv:window-pane, used when you want a pane of a frame that understands 
everything that tvrwindow does, is defined as follows: 
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(def flavor tv: window-pane () (tv:pane-mixin tv:window)) 

Among other things, tv:pane-mixin provides methods that let the pane 
participate in its superior's activity. The :alias-for-selected-windows 
method returns the superior's alias. When a window of this flavor receives a 
rselect message, it first sends its superior an :inferior-select message. If 
the tinferior-select message returns nil, the rselect message fails and just 
returns nil. When a window of this flavor receives a :mouse-select 
message, it passes the message on to its superior. 

tv:pane-no-mouse-select-mixin Flavor 

A mixin flavor to make a window a pane of a frame and ensure that it 
cannot be selected from a system menu. This flavor includes tv:pane-mixin 
and tv:dont-select-with-mouse-mixin. 

tv:window-pane Flavor 

An instantiable flavor that includes tvtpane-mixin and tv:window. 

The flavor of the frame itself might be any of several flavors. The simplest flavor of 
constraint frame is tv:constraint-frame. 

tv:basic-frame Flavor 

This flavor provides methods that allow the frame to serve as the 
representative window of its activity. Usually a frame cannot become the 
selected window, but this flavor provides methods that handle messages about 
selection, typically by operating on the selected-pane instead of the frame. 
The .-select, .'deselect, and rselect-relative methods just pass these 
messages on to the selected-pane when one exists; otherwise they return nil. 

This flavor provides a handler for the :select-pane message that decides 
which pane should be selected when the activity is selected. The 
:inferior-select method saves the argument as the selected-pane and sends 
the message on to the frame's superior with the frame as argument. The 
:name-for-selection method returns the name-for-selection of the selected- 
pane if a selected-pane exists and has a name-for-selection; otherwise, the 
method returns the name of the frame. 

tv:constraint-frame Flavor 

This flavor is the basic kind of constraint frame. A frame of this flavor is 
built out of almost the same facilities as is tv:minimum-window; the frame 
does not have all the mixins that go into the tv:window flavor. In 
particular, it will not have any borders or a label. It also has 
tv:pop-up-notification-mixin as a component. 

tv:bordered-constraint-frame Flavor 

This flavor is just tv:constraint-frame with tv:borders-mixin mixed in at 
the right place. It will have a border around the edge. By default (using the 
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:default-init-plist option of the flavor system), the :border-margin-width 
is zero, so the panes at the edges of the frame are right next to the border 
itself. 

Bordered constraint frames are used most often. Usually, each of the panes has 
borders, and the frame does too. A reason for this is that when two of the panes 
are right next to each other, as they usually are, their borders are side by side, and 
so look like a double-thick line. In order to make the edges of the panes that are at 
the edge of the frame (rather than up against another pane) look as if they are the 
same thickness, the frame has a border itself. 

It is common in frame-oriented interactive subsystems for all of the panes to use the 
same I/O buffer. The reason for this is that such subsystems are usually organized 
as a single process that reads commands and executes them. But with a many- 
paned frame, there may be many windows (each pane is a window) at which 
characters might be typed or mouse-clicks might be clicked. When the process is 
waiting for its next command, it would be inconvenient for it to have to wait for the 
complex condition that any of these windows has input available in its I/O buffer. 
Instead, since the command stream is only one serial stream of commands anyway, 
it is common to have all the panes of a frame share the same I/O buffer. 

What happens when many windows share an I/O buffer is that any characters typed 
at any of them, or any mouse-clicks that generate forced keyboard input, are all put 
into the same I/O buffer, in the chronological order in which they are generated. 
The process then does successive :tyi stream operations from any pane of the frame, 
and it receives anything that has been typed at any pane. When the I/O buffer is 
shared like this, it doesn't matter which pane is selected: All the characters go to 
the same place anyway, and the information as to which pane was typed at is lost. 
However, the forced keyboard input generated by mouse clicks at a facility that is 
designed to be used as a pane of a frame (tv:command-menu-pane for instance) 
will return all useful and relevant information to the sender of the :tyi message, 
including which pane the mouse was pointing at when it was clicked. 

To have all of the panes share the same I/O buffer, use one of the following flavors: 

tv:constraint-frame-with-shared-io-buffer Flavor 

This is like tv:constraint-frame, but all the panes of the frame share the 
same I/O buffer used by the frame itself. However, the frame does not have 
tv:stream-mixin as a component, and it does not handle :any-tyi and :tyi 

messages. 

tv:bordered-constraint-frame-with-shared-io-buffer Flavor 

This is just like tv:constraint-frame-with-shared-io-buffer except that it 
has tvrborders-mixin mixed into it at the right place, so that the frame has 
a border around it. 
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:io-buffer io-buffer (for Init Option 

tvconstraint-frame-with-shared-io-buffer) 

If this option is present, io-buffer is used as the I/O buffer for the frame and 
the panes. Otherwise, a default I/O buffer is created. 

12.16.2 Specifying Panes and Constraints 

This section gives the complete rules for specifying the panes of a constraint frame 
and for the constraint language. 

When you create a constraint frame, you must supply two initialization options. The 
rpanes option specifies what panes you want the frame to have, and the 
configurations option specifies the set of constraints for each of the configurations 
that the window may assume. For the purposes of these two options, windows are 
given internal names, which are Lisp symbols, used only by the flavors and methods 
that deal with constraint frames. These names are not used as the actual names of 
the windows (as in the :name message). 

rpanes pane-descriptions (for tv:basic-constraint-frame) Init Option 

This initialization option is required for all flavors of constraint frames. The 
argument, pane-descriptions , is a list of pane descriptions. Every pane 
description looks like this: 

(name flavor . options) 

name is the internal name (a symbol), flavor is the flavor of which the pane 
should be an instance, options is a list to be appended to the initialization 
plist for the pane when it is created. When the frame is first created, it will 
create all of its panes, using the flavor and options. The frame will add some 
of its own options to control the position and shape of the window; you 
should not pass any such options in the options list. 

configurations configuration-specification-list (for Init Option 

tvrbasic-constraint-frame) 
The configurations init option to a constraint frame controls the sizes and 
arrangement of the panes in each possible configuration of the frame. It is 
required for all flavors of constraint frames. 

In earlier releases, equivalent information was required to be specified under 
the constraints init option; it is still accepted for compatibility. See the 
section "Specifying Panes and Constraints Before Release 6.0", page 188. To 
convert a constraints option to a configurations option: See the function 
tv:back-convert-constraints, page 195. 

The value of the -.configurations init option is an alist that associates 
configuration names with configuration specifications. Each configuration 
specification consists of a list of layout specifications and a list of size 
specifications. Thus the skeleton of a typical configurations argument to 
tv:make-window looks like: 
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rconfigurations *( (main-configuration 

(: layout spec spec...) 
(:sizes spec spec...)) 
( al ternate-conf i gurati on 
(: layout spec spec.) 
(:sizes spec spec...))) 

The :layout and rsizes clauses may appear in either order. 

A configuration arranges entities within the frame. Each entity has a name 
(a symbol). There are four kinds of entity: 

pane A window inferior to the frame. 

row A linear arrangement of entities, side by side. All the 

entities in a row are the same height. 

column A linear arrangement of entities, one above the other. All 

the entities in a column are the same width. 

fill An area that does not contain any windows, but is simply 

filled with some pattern. 

The entities in a row can be panes, fills, or columns. The entities in a 
column can be panes, fills, or rows. Rows and columns are collectively 
referred to as stacks. The subentities of a stack are referred to as the 
members of the stack. Different types of members can be mixed. 

Configuration specifications have certain restrictions. All names used in a 
configuration specification must be defined as entities exactly once within that 
specification. Each entity must be used as a member of a stack exactly once, 
except for the entity with the same name as the configuration, which must 
not be a member of any stack. No stack can contain itself, directly or 
indirectly. 

12.16.2.1 ilayout Constraint Frame Specification 

A configuration is itself a stack. Thus, the symbol that names a configuration must 
appear in that configuration's rlayout list as the name of either a row or a column. 

A configuration specification includes a list of layout specifications, introduced by the 
keyword :layout. Each layout specification defines one row, column, or fill. (The 
panes are defined by the :panes init option to the frame. See the init option 
Omethod tv:basic-constraint-frame :panes), page 179.) 

A layout specification for a row takes the following form: 

(name :row namel name2...) 

name is a symbol, the name of the row. namel, name2 y and so on are symbols, the 
names of the members of the row. The members are listed in left-to-right order. 

A layout specification for a column takes the following form: 
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(name : column namel name2...) 

name is a symbol, the name of the column, namel, name2, and so on are symbols, 
the names of the members of the column. The members are listed in top-to-bottom 
order. 

A layout specification for a fill takes one of the following forms. In each of these 
name is a symbol, the name of the fill. 

(name :fill :white) 

The area is filled with zero pixels (normally displayed as white). 

(name :fill :black) 

The area is filled with one pixels (normally displayed as black). 

(name :fill array) The area is filled with the contents of the array, using bitblt. 

You probably want to use backquote (•) to create the configuration 
description and insert the array at the appropriate point. 

(name rfill symbol) 

The symbol should be the name of a function of six arguments. 
The function is expected to fill the rectangle that has been 
allocated to this part of the section with some pattern. The 
following values are passed to the function: 

constraint-node 

This is an internal data structure. You should not need to 
do anything with this argument. 

x-position 

X-coordinate of the top left corner of the rectangle to be 
filled. 

y-position 

Y-coordinate of the top left corner of the rectangle to be 
filled. 

width Width in pixels of the rectangle to be filled. 

height Height in pixels of the rectangle to be filled. 

screen-array 

This is a two-dimensional array into which the function 
should write the pattern it wants to put into the window. 

(name :fill list) This is similar to the case in which pattern is a symbol, but it lets 
you pass extra arguments. The first element of the list is the 
function to be called, and that function is passed all of the objects 
in the rest of the list, after the six arguments enumerated above. 
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12.16.2.2 :sizes Constraint Frame Specification 

A configuration specification includes a list of size specifications, introduced by the 
keyword :sizes. Each size specification defines how a stack is divided up among its 
members; it controls the width of each member of a row, or the height of each 
member of a column. No size specification exists for fills and panes. 

A size specification is a list whose first element is the name of the relevant stack. 
The remaining elements consist of groups of constraints separated by the keyword 
:then. The groups are processed sequentially; all the constraints in a group are 
processed in parallel. Each constraint allocates some of the space available in a stack 
to a single member of that stack. (This space is width if the stack is a row, height 
if the stack is a column). After one group has been processed, the amount of space 
available is decreased by the sum of the space that was allocated, and then the next 
group is processed. This is the meaning of the parallel versus sequential distinction. 

The division of constraints into groups matters when a constraint specifies the size 
of a member as some fraction of the space available. For example, suppose two 
constraints each specify that a member is to receive 50% of the available space. If 
these two constraints are in the same group (processed in parallel) they will allocate 
100% of the space. If they are in separate groups (processed sequentially) they will 
allocate 75% of the space, and the first member will be twice as large as the second 
member. The first member gets 50% of the total space, then the second member 
gets 50% of what remains, which is 25% of the total space. 

Note that the order of the constraints in a size specification is unrelated to the 
actual order of the members on the screen, which is controlled solely by the layout 
specification. 

A constraint can take any of several forms. In each case the constraint is a list 
whose first element is the name of the member (a symbol). 

(name integer) 

integer is the number of pixels to allocate. 

(name integer units) 

integer is the number of characters of width or lines of height to allocate. 
units must be :lines or characters. This form is illegal if name is not the 
name of a pane, since only panes have lines and characters. Use the 
following form if name is a stack or a fill. 

(name integer units pane) 

integer is the number of characters of width or lines of height to allocate. 
units must be .-lines or rcharacters. pane is the name of a pane that 
defines the units. Typically name is a stack and pane is a member, directly 
or indirectly, of the stack. 

(name fraction) 

fraction, a floating-point number between 0.0 and 1.0, is the proportion of the 
available space to allocate. 
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(name fraction units) 

fraction, a floating-point number between 0.0 and 1.0, is the proportion of the 
available space to allocate. The allocation is rounded down to an integral 
number of lines or characters, units must be rlines or characters. 

(name fraction units pane) 

fraction, a floating-point number between 0.0 and 1.0, is the proportion of the 
available space to allocate. The allocation is rounded down to an integral 
number of lines or characters, units must be dines or -.characters, pane is 
the name of a pane that defines the units. 

(name :even) 

The space available is divided evenly among all the constraints in the group. 
If any constraint in a group uses teven, every constraint in that group must 
use :even. Such a group must be the last group in a size specification. If 
the space available is not exactly divisible by the number of constraints in the 
group, the division is slightly uneven so that exactly all of the space will be 
used, leaving no unsightly gaps or overlaps. 

It is usually a good idea to use :even for at least one pane in every 
configuration, so that the entire frame will be taken up by panes that all fit 
together and extend to the borders of the frame. :even is careful to choose 
exactly the right number of pixels to fill the frame completely, avoiding 
roundoff errors that might cause an unsightly line of one or a few extra 
pixels somewhere. 

Remember that just because the :evens must be in the last descriptor group 
does not mean that the panes that they apply to must be at the bottom or 
right-hand end of the frame! The ordering of the panes in the frame is 
controlled by the ordering list, not by the order in which the descriptors 
appear. 

(name task message-name arg-1 arg-2 ...) 

This constraint lets you ask the window how much space it would like to 
take up. 

A message whose name is message-name and whose arguments are some 
extra arguments passed by the constraint mechanism followed by arg-1, 
arg-2, and so on, is sent to the pane; its answer says how much space the 
pane should take up. Note that arg-1, and so on, are not forms: They are 
the values of the arguments themselves (that is, they are not evaluated; if 
you want to compute them, you must build the constraint language 
description at run-time, which is usually written using a backquoted list). 

The arguments that are actually sent along with the message are the same 
as the arguments passed when you use the :funcall constraint except that 
the constraint-node is not passed. You don't have to worry about these 
unless you want to define your own methods to be used by :ask constraints, 
and definition of new methods is not documented here. 
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Various different flavors of windows accept some messages suitable for use 
with :ask. By convention, several kinds of windows, such as menus, accept a 
message called :pane-size. For example, the :pane-size method for menus 
figures out how much space in the dimension controlled by the task 
constraint is needed to display all the items of the menu, given the amount 
of space available in the other dimension. No arguments are specified in the 
constraint. Another useful message, handled by tv:pane-mixin (and 
therefore by all panes) is :square-pane-size (also with no arguments), which 
makes the window take up enough room to be square. 

(name :ask- window pane-name message-name arg-1 arg-2 ...) 

This constraint works like :ask except that the message is sent to the pane 
named pane-name instead of the pane being described. This is primarily used 
for stacks, when the size of a stack should be controlled by the needs of a 
pane inside it. 

(name :funcall function arg-1 arg-2 ...) 

This constraint lets you supply a function to be called, which should compute 
the amount of space to use. The rfuncall constraint is rarely used and you 
probably don't need to worry about it. The specified function is called. It is 
first passed six arguments from inside the workings of constraint frames, and 
then the arg-1, arg-2, and so on, values. The six arguments are: 

constraint-node 

This is an internal data structure. You should not need to do 
anything with this argument. 

remaining-width 

The amount of width remaining to be used up at the time this 
description is elaborated, after all of the panes in previous description 
groups and all of the earlier panes in this description group are 
allocated. 

remaining-height 

Like remaining-width, but in the height direction. 

total-width 

The amount of width remaining to be used up by all of the parts of 
this description group. This is the amount of room left after all of 
the panes in previous description groups have been allocated but none 
of the panes in this description group have been allocated. 

total-height 

Like total-width, but in the height direction. 

stacking 

Either rvertical or horizontal, depending on the current stacking. 

(name :eval form) 

This is like rfuncall, but instead of providing a function and arguments, you 



185 
March 1985 Using the Window System 



provide a form. The :eval constraint is rarely used and you probably don't 
need to worry about it. The six special values that are passed as arguments 
when the rfuncall constraint-type is used can be accessed by form as the 
values of the following special variables: 

tv:**constraint-node** 

tv:**constraint-remaining-width** 

tv:**constraint-remaining-height** 

tv:**constraint-total-width** 

tv:**constraint-total-height** 

tv:**constraint-stacking** 

(name :limit (min max) rest-of-the-constraint...) 

Any constraint may, optionally, be preceded by a :limit clause. The :limit 
clause lets you set a minimum and a maximum value that will be applied to 
the size computed by the constraint. If the constraint returns a value 
smaller than the minimum, then the minimum value will be used; if it 
returns a value larger than the maximum, then the maximum value will be 
used. The limit-specification is normally a two-element list, whose elements 
are integers giving the minimum and maximum values in pixels. 

(name :limit (min max units) rest-of-the-constraint...) 

If the list has a third element, it should be one of the symbols :lines or 
characters, and it means that the integers are in units of lines or 
characters, computed by multiplying by the line-height or char-width of the 
pane. 

(name rlimit (min max units pane) rest-of-the-constraint...) 

If there is a fourth element, it should be the name of a pane, and that 
pane's line-height or char-width is used instead of that of the pane being 
constrained. (If this constraint applies to a stack instead of a pane, and the 
third element of the list is present, then the fourth must be present as well, 
since stacks do not have their own line-height or char-width.) 

For example, to make a pane called interactor the same height as a pane 
menu as long as that size is between 10 and 20 lines, you might use 

(interactor rlimit (10 20 rlines) 

:ask-window menu :pane-size) 

12.16.3 Examples of Specifications of Panes and Constraints 

Following are examples of configuration definitions, slightly edited from the system 
source code. 

Here is how the Font Editor (FED) specifies its standard configuration. This code is 
extracted from a source file with package fed and base 8. 
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(defmethod (fed :before :init) (init-plist) 

(setf (get init-plist rconfigurations) 
*(( : standard 
(: layout 
(: standard :column character-pane prompt-pane top-section) 
(top-section :row fed-pane other-slab) 
(other-slab :column 

draw-mode-menu 
command-menu- 1 
command-menu-2 
command-menu-3 
status-pane 
alphabet-menu 
param-chw 
register-pane)) 
(tsizes 
(other-slab (draw-mode-menu :ask :pane-size) 

:then ( command-menu- 1 :ask :pane-size) 
:then (command-menu-2 :ask -.pane-size) 
:then (command-menu-3 :ask :pane-size) 
:then (status-pane 3 : lines) 
:then (alphabet-menu :ask :pane-size) 
:then (param-chw 5 : lines) 
:then (register-pane :even)) 
(top-section (other-slab : limit (24 144 :characters prompt-pane) 

0.3) 
:then (fed-pane :even)) 
( rstandard 
(character-pane :ask :wanted-size) 
:then (prompt-pane 4 : lines) 
:then (top-section :even)))) 
(:wide ...)))) 

Here is how an early implementation of the Document Examiner specified its frame 
configuration. This code is extracted from a source file with package sage and base 
10. 
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(def const *dex- frame-constraints* 
'((main 
( : layout 
(main :column top-part bottom-part) 

(top-part :row title&viewer-pane candidates-and-bookmarks) 
(bottom-part :row command-pane menu-pane) 
(title&viewer-pane rcolumn title-pane viewer-pane) 
(candidates-and-bookmarks rcolumn candidate-pane bookmark-pane)) 
( :sizes 
(main (bottom-part 4 .-lines command-pane) 

:then (top-part reven)) 
(bottom-part (command-pane 660) 

:then (menu-pane :even)) 
(top-part (title&viewer-pane 660) 

:then (candidates-and-bookmarks :even)) 
(title&viewer-pane (title-pane : lines) ; label only 

rthen (viewer-pane reven)) 
(candidates-and-bookmarks (candidate-pane 0.5) 

rthen (bookmark-pane reven)))))) 

(defmethod (dex-frame rbefore rinit) (plist) 
(unless (variable-boundp tvrpanes) 

(setq tvrpanes *dex- frame-panes*)) 
(unless (get plist rconfigurations) 

(setf (get plist rconfigurations) *dex-frame-constraints*)) 
...) 

12.16.4 Messages to Frames 

:select-pane pane Message 

The :select-pane message to a frame makes pane the selected-pane of the 
frame, pane must be either an exposed inferior of the frame or nil, which 
means to set the selected-pane to nil. This message also deselects the 
current selected-pane if it is a window different from pane. Unless pane is 
nil, this message sends pane a rselect-relative message. 

:selected-pane Message 

The :selected-pane message to a frame returns the selected-pane of the 
frame. This message is sent by users and received by the system. 

:selected-pane pane (for tv:basic-constraint-frame) Init Option 

Makes pane the selected-pane of this frame, pane can be the symbol used in 
the tpanes init option to name the pane. 

:get-pane pane-name of tv:basic-constraint-frame Method 

Return the pane (the inferior window itself) that was named by the symbol 
pane-name in the :panes specification of this frame. 
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:pane-name pane of tv:basic-constraint-frame Method 

Return the symbol that was used to name pane in the rpanes specification of 
this frame. If pane is not one of the panes, return nil. 

:send-pane pane-name message &rest arguments of Method 

tv:basic-constraint-frame 

Send the specified message with the specified arguments to the pane that 
was named by the symbol pane-name in the rpanes specification of this 
frame. 

:send-all-panes message &rest arguments of Method 

tv:basic-constraint-frame 

Send the specified message with the specified arguments to all of the panes of 
this frame, including the nonexposed ones. 

:send-all-exposed-panes message &rest arguments of Method 

tv:basic-constraint-frame 

Send the specified message with the specified arguments to all of the exposed 
panes of this frame. 

configuration configuration-name (for Init Option 

tv:basic-constraint-frame) 

Make the initial configuration of the frame be the one named by the symbol 
configuration-name. 

configuration of tv:basic-constraint-frame Method 

Return the symbol naming the current configuration of the frame. 

:set-configuration configuration-name of Method 

tv:basic-constraint-frame 

Set the configuration of the frame to the one named by the symbol 
configuration-name. 

12.16.5 Specifying Panes and Constraints Before Release 6.0 

This section gives the complete rules for specifying the panes of a constraint frame, 
and for the constraint language, in releases before 6.0. The specification method 
described in this section is obsolete but supported in Release 6.0 for compatibility. 
For a description of how to specify panes and constraints in Release 6.0: See the 
section "Specifying Panes and Constraints", page 179. 

When you create a constraint frame, you must supply two initialization options. The 
rpanes option specifies what panes you want the frame to have, and the 
constraints option specifies the set of constraints for each of the configurations 
that the window may assume. For the purposes of these two options, windows are 
given internal names, which are Lisp symbols, used only by the flavors and methods 
that deal with constraint frames. These names are not used as the actual names of 
the windows (as in the :name message). 
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:panes pane-descriptions (for tv:basic-constraint-frame) Init Option 

This initialization option is required for all flavors of constraint frames. The 
argument, pane-descriptions, is a list of pane descriptions. Every pane 
description looks like this: 

(name flavor . options) 

name is the internal name (a symbol), flavor is the flavor of which the pane 
should be an instance, options is a list to be appended to the initialization 
plist for the pane when it is created. When the frame is first created, it will 
create all of its panes, using the flavor and options. The frame will add some 
of its own options to control the position and shape of the window; you 
should not pass any such options in the options list. 

constraints configuration-description-list (for Init Option 

tv:basic-constraint-frame) 
This initialization option was required for all flavors of constraint frames 
before Release 6.0. It has been replaced by the configurations init option. 
See the init option (: method tv:basic-constraint-frame configurations), 
page 179. To convert a constraints option to a configurations option: 
See the function tv:back-convert-constraints, page 195. 

The argument, configuration-description-list , is a list of configuration 
descriptions. For the format of configuration descriptions: See the section 
"Specifying Panes and Constraints Before Release 6.0", page 188. 

A configuration-description-list is a list of configuration-descriptions. There is one 
configuration-description in the list for each of the possible configurations that the 
frame can assume. Each configuration is named by a symbol, called the 
configuration-name. A configuration-description-list is an alist that associates the 
configuration-descriptions with the names. It looks like this: 

({configuration-name-1 . configuration-description-1) 
(configuration-name-2 . configuration-description-2) 
...) 

Each configuration-description describes the layout of the panes in a single 
configuration. The description has two parts. The first part specifies the order in 
which the windows appear, and the second part specifies how the sizes are 
computed. Actually, in addition to windows, there can also be dummies in the 
configuration-descriptor. A dummy is used either to hold empty space that is not 
used by any window, or it can reserve a region of space to be divided up by another 
configuration-description. 

A configuration-description splits up one of the dimensions of a rectangular area into 
many parts. Such an area is called a section. Which of the two dimensions is being 
split up is determined by the stacking. If the stacking is :vertical then the section 
is being split up vertically; that is, the parts are stacked on top of each other. If the 
stacking is :horizontal then the section is being split up horizontally; that is, the 
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parts are side-by-side. The stacking of the top-level configuration-descriptions in the 
constraints option is always rvertical, but there can be more configuration- 
descriptions nested inside of them, and these can have either stacking. 

Each part has a name, represented as a symbol. A part may either hold an actual 
pane, or it may hold something else; if it holds something else, it is called a dummy 
part. Dummy parts can be further subdivided into more panes and dummies using 
another constraint-description, or their pixels can be blank or filled with some 
pattern. 

A configuration-description looks like this: 
(ordering . description-groups) 

ordering is a list of names of panes and of dummies, each represented by a symbol; 
the order of this list is the order that the panes and dummies appear in the space 
being split up by the configuration-description. For vertical stacking the list goes top 
to bottom. For horizontal stacking the list goes left to right. A description-group is 
a list of descriptions. Each description describes either exactly one pane or one 
dummy. A configuration-description must have one description for each element of 
the ordering list. 

All of the descriptions in a description-group are processed together ("in parallel"); 
each of the description-groups is processed in turn, starting with the first one. By 
grouping the descriptions this way, you can control which constraints are elaborated 
together and which are elaborated at different times; when two constraints are 
elaborated at different times you can control which one is elaborated first. The 
reason that the ordering-list in the configuration-description is separate from the 
description-groups is so that the order in which the panes and dummies appear in 
the frame can be independent of the order in which their constraints are elaborated. 

Each description describes one pane or one dummy. We'll get back to dummies 
later. A description that describes a pane looks like this: 

(pane-name . constraint) 

pane-name is the name of the pane being described; constraint is the constraint that 
describes the pane. We will return later to what descriptions of dummies look like. 
The constraint will be elaborated, and will yield a size in pixels; this size will be used 
for the width or height being computed. 

Finally we get to constraints themselves. The basic form of a constraint is as 
follows: 

(key arg-1 arg-2 ...) 

key may be an integer, a flonum, or one of various keyword symbols. Each type of 
constraint may take arguments, whose meaning depends on which kind of constraint 
this argument is passed to. 

While descriptions of panes do not have the same format as descriptions of dummies, 
the same kind of constraints are used in both of them. So all the formats given 
below may be used inside the descriptions of either panes or dummies. 
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Any constraint may, optionally, be preceded by a :limit clause. If a constraint has a 
:limit clause, the constraint looks like: 

(.•limit limit-specification key arg-1 arg-2 ...) 

The :limit clause lets you set a minimum and a maximum value that will be applied 
to the size computed by the constraint. If the constraint returns a value smaller 
than the minimum, then the minimum value will be used; if it returns a value 
larger than the maximum, then the maximum value will be used. The 
limit-specification is normally a two-element list, whose elements are integers giving 
the minimum and maximum values in pixels. If the list has a third element, it 
should be one of the symbols :lines or characters, and it means that the integers 
are in units of lines or characters, computed by multiplying by the line-height or 
char-width of the pane. If there is a fourth element, it should be the name of a 
pane, and that pane's line-height or char-width is used instead of that of the pane 
being constrained. (If this constraint applies to a dummy instead of a pane, and the 
third element of the list is present, then the fourth must be present as well, since 
dummies do not have their own line-height or char-width.) 

The following Lisp objects may be used as values of key in a constraint. Note: The 
:funcall and :eval constraints are rarely used and you probably don't need to worry 
about them. The other kinds are used frequently. 

integer This lets you specify the absolute size. The value computed by the 

constraint is simply this integer. Optionally, an argument may be given: it 
may be the symbol dines or the symbol characters, meaning that the 
integer is in units of lines or characters, and should be computed by 
multiplying by the line-height or char-width of the window. If a second 
argument is also present, it should be the name of a pane, and that pane's 
line-height or char-width is used instead of that of the pane being 
constrained. (If this constraint applies to a dummy instead of a pane, and 
the first argument is given, then the second must be present as well, since 
dummies do not have their own line-height or char-width.) 

flonum This lets you specify that a certain fraction of the remaining space should be 
taken up by this window. Optionally, an argument may be given: It may be 
dines or characters, and it means to round down the size of the pane to 
the nearest multiple of the pane's line-height or char-width. A second 
argument may be given; it is just like the second argument when key is an 
integer. 

The distinction between descriptors in the same group and descriptors in 
different groups is important when you use this kind of constraint. If you 
have one descriptor group with two descriptors, both of which requests .2 of 
the remaining space, then both panes will get the same amount of space. 
However, if you have the same two descriptors but put them in successive 
descriptor groups, then the first one will get .2 of the remaining space, and 
then the second one will get .2 of what remains after the first one was 
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allocated; thus, the second pane will be smaller than the first pane. In other 
words, the amount of space remaining is recomputed at the end of each 
descriptor group, but not at the end of each descriptor. 

:even This constraint has a special restriction: You can only use it for descriptors 
in the last descriptor group of a configuration. Furthermore, if any of the 
descriptors in that group use :even, then all of the descriptors in the group 
must use :even. The meaning is that all of the panes in the last descriptor 
group evenly divide all of the remaining space. 

It is usually a good idea to use :even for at least one pane in every 
configuration, so that the entire frame will be taken up by panes that all fit 
together and extend to the borders of the frame. :even is careful to choose 
exactly the right number of pixels to fill the frame completely, avoiding 
roundoff errors that might cause an unsightly line of one or a few extra 
pixels somewhere. 

Remember that just because the tevens must be in the last descriptor group 
does not mean that the panes that they apply to must be at the bottom or 
right-hand end of the frame! The ordering of the panes in the frame is 
controlled by the ordering list, not by the order in which the descriptors 
appear. 

task This constraint lets you ask the window how much space it would like to 
take up. The format of a constraint using task is as follows: 

(:ask message-name arg-1 arg-2 ...) 

A message whose name is message-name and whose arguments are some 
extra arguments passed by the constraint mechanism followed by arg-1, 
arg-2, and so on, is sent to the pane; its answer says how much space the 
pane should take up. Note that arg-1 , and so on, are not forms: They are 
the values of the arguments themselves (that is, they are not evaluated; if 
you want to compute them, you must build the constraint language 
description at run-time, which is usually written using a backquoted list). 

The arguments that are actually sent along with the message are the same 
as the arguments passed when you use the tfuncall option except that the 
constraint-node is not passed; see below. You don't have to worry about 
these unless you want to define your own methods to be used by task 
constraints, and definition of new methods is generally beyond the scope of 
this document anyway. 

Various different flavors of windows accept some messages suitable for use 
with task. By convention, several kinds of windows, such as menus, accept a 
message called :pane-size. For example, the :pane-size method for menus 
figures out how much space in the dimension controlled by the task 
constraint is needed to display all the items of the menu, given the amount 
of space available in the other dimension. No arguments are specified in the 
constraint. Another useful message, handled by tv.pane-mixin (and 
therefore by all panes) is tsquare-pane-size (also with no arguments), which 
makes the window take up enough room to be square. 
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:ask-window 

This constraint is a variation on task. Its format is: 

(:ask pane-name message-name arg-1 arg-2 ...) 

It works like task except that the message is sent to the pane named 
pane-name instead of the pane being described. This is primarily used for 
dummies, when the size of a dummy should be controlled by the needs of a 
pane inside it. 

tfuncall 

This constraint lets you supply a function to be called, which should compute 
the amount of space to use. The format is: 

(rfuncall function arg-1 arg-2 ...) 

The specified function is called. It is first passed six arguments from inside 
the workings of constraint frames, and then the arg-l y arg-2 y and so on, 
values. The six arguments are: 

constraint-node 

This is an internal data structure. [Not yet documented; you should 
not need to look at this anyway.] 

remaining-width 

The amount of width remaining to be used up at the time this 
description is elaborated, after all of the panes in previous description 
groups and all of the earlier panes in this description group are 
allocated. 

remaining-height 

Like remaining-width, but in the height direction. 

total-width 

The amount of width remaining to be used up by all of the parts of 
this description group. This is the amount of room left after all of 
the panes in previous description groups have been allocated but none 
of the panes in this description group have been allocated. 

total-height 

Like total-width, but in the height direction. 

stacking 

Either tvertical or horizontal, depending on the current stacking. 

reval This is like rfuncall, but instead of providing a function and arguments, you 
provide a form. The format is: 

(:eval form) 

The six special values that are passed as arguments when the :funcall 
constraint-type is used can be accessed by form as the values of the following 
special variables: 
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tv:**constraint-node** 

tv:* *constraint-remaining-width** 

tv:**constraint-remaining-height** 

tv:**constraint-total-width** 

tv:**constraint-total-height** 

tv:**constraint-stacking** 

This finishes the discussion of descriptions of panes. Descriptions of dummies are 
different; they may be in any of several formats, identified by the following 
keywords: 

:blank This description is used if you want this part of the section to be filled up 
with some constant pattern. The format of the description is: 

(dummy-name : blank pattern . constraint) 

The constraint is used to figure out the size of the part of the section, in the 
usual way. pattern may be any of the following: 

:white The part is filled with zeroes. 

rblack The part is filled with the maximum value that the pixels can hold (if 
the pixels are one bit wide, as on a black-and-white TV, this value is 
1). 

an array 

The part is filled with the contents of the array, using the bitblt 
function. 

a symbol 

The symbol should be the name of a function of six arguments. The 
function is expected to fill up the rectangle that has been allocated to 
this part of the section with some pattern. The following values are 
passed to the function: 

constraint-node 

This is an internal data structure. [Not yet documented; you 
should not need to look at this anyway.] 

x-position 

y-position 

width 

height These four arguments tell the function the position and size of 
the rectangle that it should fill. 

screen-array 

This is a two-dimensional array into which the function should 
write the pattern it wants to put into the window. 
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a list This is similar to the case in which pattern is a symbol, but it lets you 
pass extra arguments. The first element of the list is the function to 
be called, and that function is passed all of the objects in the rest of 
the list, after the six arguments enumerated above. 

horizontal or rvertical 

This description is used if you want to subdivide the part into more panes 
and dummies, using a configuration-description. If you use rvertical, it will 
be split up with vertical stacking, and if you use :horizontal, it will be split 
up with horizontal stacking. You must use only the opposite kind of stacking 
from the kind currently happening; that is, successive levels of configuration- 
description must use alternating kinds of stacking. The format is as follows: 

(dummy-name rhorizontal constraint . configuration-description) 

or 

(dummy-name rvertical constraint . configuration-description) 

constraint, as usual, specifies the size of this part; it can be in any of the 
formats given above. Note that in this format, constraint appears as an 
element of a list rather than as the tail of a list, and so the printed 
representation of the list will include a pair of parentheses around the 
constraint, configuration-description tells how this part is subdivided into 
parts of its own. 

tv:back-convert-constraints constraints Function 

Converts a list used as the :constraints init option for 
tvrbasic-constraint-frame to a list suitable for the configurations option. 
The configurations option replaced the constraints option in Release 6.0. 

The function returns two values: a list suitable for use as the argument to 
the configurations option, and a list of symbols naming the panes 
encountered in the list. 



Example: 



( tv: back-convert-constrai nts 

* ((first-config . ((top-strip main-pane) 

((top-strip rhorizontal (.3) 
(huey dewey louie) 
((huey :even) 
(dewey :even) 
(louie :even)))) 
((main-pane :even)))) 
(second-config . ((main-pane bottom-strip) 

((bottom-strip : horizontal (.2) 
(random-pane menu) 
((menu :ask :pane-size)) 
((random-pane -.even)))) 
((main-pane :even)))))) 
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-> ((first-config (: layout 

(first-config rcolumn top-strip main-pane) 
(top-strip :row huey dewey louie)) 
(:sizes 

(top-strip (huey :even) (dewey :even) (louie :even)) 
(first-config (top-strip 0.3) 

:then (main-pane :even)))) 
(second-config (: layout 

(second-config : column main-pane bottom-strip) 
(bottom-strip :row random-pane menu)) 
(:sizes 
(bottom-strip (menu :ask :pane-size) 

:then (random-pane :even)) 
(second-config (bottom-strip 0.2) 

:then (main-pane :even))))) 

(random-pane menu main-pane louie dewey huey) 

12.16.6 Examples of Specifications of Panes and Constraints Before Release 6.0 

This section gives some examples of specifications of panes and constraints in the 
constraint language used before Release 6.0. The full description of how to use 
constraint frames, including the full constraint language, is rather complicated. For 
complete specifications of the pre-Release 6.0 language: See the section "Specifying 
Panes and Constraints Before Release 6.0", page 188. For the constraint language 
used in Release 6.0: See the section "Specifying Panes and Constraints", page 179. 

The following form creates a constraint frame with two panes, one on top of the 
other, each of which takes up half of the frame. 

(tv: make-window 'tv: constraint- frame 
• : panes 

* ((top-pane tv.window-pane) 
(bottom-pane tv: window-pane)) 
• : constraints 

'((main . ((top-pane bottom-pane) 
((top-pane 0.5)) 
((bottom-pane :even)))))) 

Two initialization options were given to the tv:constraint-frame flavor: the rpanes 
option and the constraints option. The meaning of the rpanes specification is: 
"This frame is made of the following panes. Call the first one top-pane; its flavor is 
tv: window. Call the second one bottom-pane; its flavor is tvrwindow". The 
meaning of the rconstraints specification is: "There is just one configuration 
defined for this pane; call it main. In this configuration, the panes that appear are, 
in order from top to bottom, top-pane and bottom-pane, top-pane should use up 
0.5 of the room, bottom-pane should use up all the rest of the room." 
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This example demonstrates some more features: 

(tv: make-window 

'tvcbordered-constraint- frame 
* : panes 
'((graphics-pane tv:window-pane 
:label nil :blinker-p nil ) 
(message-pane tv:window-pane 

: label "Message Pane" :blinker-p nil) 
(interaction-pane tv:window-pane)) 
* : constraints 
'((main . ((interaction-pane graphics-pane message-pane) 
((message-pane 4 : lines)) 
((graphics-pane 400)) 
((interaction-pane :even)))))) 

This frame has a border around the edges (because of the flavor of the frame itself), 
and it has three panes. The panes are given some initialization options themselves. 
The topmost pane is interaction-pane, graphics-pane is in the middle, and 
message-pane is on the bottom, message-pane is four lines high, graphics-pane 
is 400 pixels high, and interaction-pane uses up all remaining space. 

Here is a window that has two possible configurations. In the first one, there are 
three little windows across the top of the frame and a big window beneath them; in 
the second one, the same big window is at the top of the frame, and underneath it 
is a strip split between a menu and another window. 
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(tv: make-window 

*tv: bordered- constraint- frame 
* : panes 
'((huey tv.-window-pane) 
(dewey tv:window-pane) 
(louie tv:window-pane) 
(main-pane tv:window-pane) 
(random-pane tv:window-pane) 
(menu tv: command-menu-pane 

:i tern- list ("Foo" "Bar" "Baz"))) 
' constraints 
'((first-config . ((top-strip main-pane) 

((top-strip rhorizontal (.3) 
(huey dewey louie) 
((huey :even) 
(dewey :even) 
(louie :even)))) 
((main-pane :even)))) 
(second-config . ((main-pane bottom-strip) 

((bottom-strip rhorizontal (.2) 
(random-pane menu) 
((menu :ask :pane-size)) 
((random-pane :even)))) 
((main-pane :even)))))) 

In this example, the frame has two different configurations. When the frame is 
first created, it will be in the first of the configurations listed, namely first-config. 
In this configuration, the top three-tenths of the frame are split equally, 
horizontally, between three windows, and the rest of the frame is occupied by 
main-pane. The frame can be switched to a new configuration using the 
:set-configuration message. If we switch it to second-config, then main-frame 
will appear on top of a strip one-fifth of the height of the window. This strip will 
contain a menu on the right that is just wide enough to display the strings in the 
menu's item list, and another pane using up the rest of the strip. When the 
configuration of the window is switched, main-pane must be reshaped. 

Another thing to notice is that the list of items in the menu was present in the 
:panes option, rather than a form to be evaluated. If the list had been in a 
variable, it would have been necessary to write the :panes option using backquote, 
like this: 

' : panes 

*((huey tv:window-pane) 
(dewey tv:window-pane) 
(louie tv:window-pane) 
(main-pane tv:window-pane) 
(random-pane tv:window-pane) 
(menu tv: command-menu-pane 

:i tern- list , the- list-of-i terns)) 
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For an explanation of how to use menus: See the section "Window System Choice 
Facilities", page 201. 

Following is the last example, using the configurations init option instead of the 
constraints option used before Release 6.0: 

(tv: make-window 

'tv:bordered-constraint- frame 
* : panes 

'((huey tv:window-pane) 
(dewey tv: window-pane) 
(louie tv:window-pane) 
(main-pane tv:window-pane) 
(random-pane tv: window-pane) 
(menu tv: command-menu-pane 

:i tern- list ("Foo" "Bar" "Baz"))) 
' configurations 
'((first-config (: layout 

(first-config :column top-strip main-pane) 
(top-strip :row huey dewey louie)) 
( :sizes 

(top-strip (huey :even) (dewey :even) (louie :even)) 
(first-config (top-strip 0.3) 

:then (main-pane :even)))) 
(second-config (: layout 

(second-config :column main-pane bottom-strip) 
(bottom-strip :row random-pane menu)) 
(.•sizes 
(bottom-strip (menu :ask :pane-size) 

:then (random-pane :even)) 
(second-config (bottom-strip 0.2) 

:then (main-pane :even)))))) 

For a description of the constraint language used in Release 6.0: See the section 
"Specifying Panes and Constraints", page 179. 

In this example, the window is divided into two windows, side by side. 

(tv: make-window 

• tv : bordered-cons trai nt- frame 
• :edges '(100 100 600 600) 
': panes 
'((left tv:window-pane) 
(right tv:window-pane)) 
^constraints 
'((main . ((whole-thing) 

((whole-thing horizontal (:even) 
(left right) 
((left :even) 
(right :even)))))))) 
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This example also points out that constraint frames are windows too, and you can 
use init options acceptable to tv:minimum-window with them. In this case, we 
give the edges of the frame as a whole, in absolute numbers. Remember that 
frames are not built out of tvrwindow. 
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Window System Choice Facilities 
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13. The Choice Facilities 



The window system for the Lisp Machine contains a variety of facilities to allow the 
user to make choices interactively. These all work by displaying some arrangement 
of items in a window. By pointing to an item with the mouse and pressing a mouse 
button, the user selects the item. The choice facilities are implemented in and 
accessed with the Flavors feature of Lisp. 



13.1 Overview of the Choice Facilities 

This section is a capsule description of the choice facilities. This should familiarize 
you with the possibilities, thereby helping you to decide which facility is appropriate 
to your application, without reading through each detailed description. 

13.1.1 List of Choice Facilities 

Here is a brief explanation of each of the choice facilities. 

Pop-up Menus 

This facility puts a menu with items on the screen. The user is forced to 
make a choice among the items. (The menu does not disappear until a choice 
has been made.) See the section "Instantiate Pop-up and Momentary 
Menus", page 221. 

Momentary Menus 

Momentary menus appear on the screen with a list of choices. The user does 
not have to make a choice, however. By moving the mouse outside of the 
menu, the user can make the menu disappear. See the section "Basic and 
Mixin Pop-up and Momentary Menus", page 220. 

Command Menus 

Command menus are used when you want to pass a command to your own 
controlling process from a menu. The command is sent to the process via an 
input buffer that can be shared with other windows or processes. This way, 
the controlling process can be looking in the buffer for commands from 
several windows as well as for keyboard input. See the section "Command 
Menus", page 229. 

Dynamic Item List Menus 

A dynamic item list menu is provided for menus whose items change over 
time. The item list is updated whenever the menu is displayed. Both 
momentary and pop-up dynamic item list menus are available. See the section 
"Dynamic Item List Menus", page 235. 
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Multiple Menus 

Multiple menus are provided for situations in which the user can select 
several items at a time. The selected items are displayed in inverse video. 
Special choices allow the user to specify operations on all the items selected. 
Both momentary and pop-up multiple menus are available. See the section 
"Multiple Menus", page 241. 

Multiple Menu Choose Menus 

This facility provides for menus with several columns. The user picks one 
item from each column. Special choices [Do It] and [Abort] are used to 
execute the choices and and deactivate the menu, respectively. See the 
section "The Multiple Menu Choose Facility", page 247. 

Multiple Choice Menus 

This facility displays a menu in which each item is displayed on a separate 
line. Each item is associated with several yes/no choices, in choice boxes. By 
pointing to a box and pressing the left mouse button, the user complements 
the yes/no state of the choice box for that item. Constraints can be imposed 
among the choices for an item, ensuring, for example, that if one box is 
selected, the others are automatically deselected. See the section "The 
Multiple Choice Facility", page 251. 

Choose Variable Values 

Each item is associated with a value printed next to it. Many different types 
of values can be specified, or the programmer can create new types. In 
operation, users select items and then alter the values associated with the 
item. See the section "The Choose Variable Values Facility", page 257. 

User Options 

The user option facility is based on the choose variable values facility. It is 
used to keep track of options to a program of the sort that users would want 
to specify once and then save. The option list can be associated with 
particular programs. See the section "The User Option Facility", page 266. 

Mouse-sensitive Items and Areas 

Mouse-sensitive behavior underlies all of the choice facilities. This mixin 
facility lets areas of the screen be sensitive to the mouse. Moving the mouse 
into such an area causes a box to be drawn around it. At this point, clicking 
the mouse invokes a user-defined operation. See the section "The Mouse- 
sensitive Items Facility", page 279. 

Margin Choices 

Windows can be augmented with choice boxes in their margins. Choice boxes 
give the user a few mouse-sensitive points that are independent of anything 
else in the window. Margin choices can be added to any flavor of window in 
a modular fashion. See the section "The Margin Choice Facility", page 289. 
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13.2 Standard and Customizable Facilities 

From the programmer's viewpoint, there are two ways of invoking the choice 
facilities. 

• Standard facilities are provided with a reasonable set of defaults predefined in 
the system code. They are invoked with a simple function call. 

• Customizable facilities require you to provide more specifications, but they allow 
more flexibility in the layout and behavior of the facilities. Customizable 
facilities are manipulated by the Flavor system, and include instantiate, basic, 
and mixin flavors. 

Many of the documented choice facilities are provided in both standard and 
customizable forms. 



13.3 Choice Facilities Use the Flavor System 

The window system and the choice facilities are implemented using the Flavor 
system in Lisp. When a menu is instantiated, users communicate with it by 
pressing mouse buttons (sometimes called "mouse-clicking"), or by typing in values. 
Internally, programs communicate with a menu by sending it a message using the 
send function of Lisp. 

Useful initialization property-list options (hereafter called init-plist options) and 
messages associated with each flavor are specified in this document. 

13.3.1 Combining Choice Facilities 

Since the choice facilities are implemented with the Flavor system, many of the 
behaviors listed previously can be integrated into one menu by means of flavor 
combination. 

For example, one menu might include both of these features: 

• Pop-up behavior, meaning that the window does not disappear until a choice 
has been made. 

• Multiple menu behavior, allowing several menu items to be selected. 

13.3.2 Instantiate, Basic, and Mixin Flavors 

Each choice facility is based on either an instantiable, a basic, or a mixin flavor. 
Even the standard choice facilities (invoked by simple Lisp function calls) are based 
on these flavors. 
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Instantiate flavors are self-contained objects that are ready to be invoked. 
Instantiate facilities are built out of the basic and mixin facilities. An example of 
an instantiate facility is the tv:momentary-menu flavor. 

Basic flavors (often denoted by the prefix basic- in the code) define a whole family 
of related flavors. Most of the basic flavors are noninstantiable and merely serve as 
a base on which to build other flavors. An example of a noninstantiable basic facility 
is the tv:basic-mouse-sensitive-items flavor. 

Mixin flavors (often denoted by the suffix -mixin in the code) define a particular 
feature of an object. A mixin flavor cannot be instantiated, because it is not a 
complete object. An example of a mixin flavor is tvrdynamic-multicolumn-mixin. 

In the descriptions of the different choice facilities that follow, the instantiate 
flavors will be discussed first, followed by the basic and mixin flavors. 

13.3.3 Modifying the Choice Facilities 

Although this document explains how to combine the features of the different choice 
facilities to suit different applications, it does not tell you how to modify the facilities 
provided with the system, except in the simplest of ways. In order to change the 
basic behavior of the choice facilities you will need to read some of the code that 
implements the facility in question. (For example, you should study window instance 
variables and internal messages that you might want to put daemons on or 
redefine.) 



13.4 The User's Process and the Mouse Process 

An asynchronous process called the mouse process handles interaction with the 
mouse. Some portions of these choice facilities execute in the process that calls 
them, while other portions execute in the mouse process. For example, when menu 
items are displayed on the screen and the mouse points to them, a box is drawn 
around the items. This drawing is performed by the mouse process. 

This document does not attempt to explain the details of how the mouse and the 
window system interact. Indeed, the choice facilities are supposed to shield the user 
from such details, and they can be used effectively with no knowledge of how they 
are implemented internally. 

However, the cases in which a portion of a facility runs in the mouse process are 
noted where they occur in this text. Excepting these cases, you can freely use side- 
effects (both special variables and throw), and not worry about errors in your 
program corrupting the system. 

The choice facilities described in this document respond to messages sent by the 
mouse process. For example, .-mouse-buttons, rmouse-click, and zmouse-select are 
all handled by any flavor built on tvrmenu. 
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14. Introduction to the Menu Facilities 



From the user's point of view, a menu is a group of choices, each identified by a 
word or short phrase. To see an example of a menu, click the right mouse button 
while in a Lisp Listener; this should cause the System menu to appear (Figure 1). 



Windows 


This window 


Programs 


Create 


Attributes 


Lisp 


Select 


Refresh 


Edit 


Split Screen 


Bury 


Inspect 


Layouts 


Kill 


Mail 


Edit Screen 


Reset 


Font Edit 


Set Mouse Screen 


Arrest 


Trace 




Un-Arrest 


Emergency Break 


X 




Flavor Examiner 

Hard copy 

File System 



Figure 1. System menu. 

You can select one of the choices by moving the mouse near it, which causes it to be 
highlighted (a box appears around it), and then clicking any mouse button. What 
happens when you select one of the choices depends on the particular type of menu. 
Typically the choices in a menu might be commands to some program or choices on 
which a command should operate. 

The window system software automatically chooses the arrangement of the choices 
and the size and shape of the window. Naturally, there are ways for programmers 
to control these parameters if they desire. See the section "Init-plist Options for 
tvrmenu", page 295. 

The inverse-video mouse documentation line is provided near the bottom of the 
screen in order to convey the meaning of the mouse buttons at a given time. For 
example, in the System menu, with the mouse positioned over the "Create" item, 
the mouse documentation line normally displays the following text: 

Create a new window. Flavor of window selected from a menu. 

The abbreviations L, M, and R stand for the left, middle, and right mouse buttons, 
respectively. The numeral 2 indicates a quick double click of the mouse button. 
(Note that the "double-click" effect can also be obtained by clicking once on the 
mouse while holding down the SHIFT key. ) 
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14.1 Components of a Menu 

It is important to understand the terminology for describing a menu. The 
components of a menu are shown in Figure 2. 



14.2 Menu Items 

From the viewpoint of the programmer, a menu has a list of items; each item 
represents one of the displayed choices. The user chooses an item, and then the 
program executes it. 

An item, then, has three parts: 

• A representation in the item list 

• A displayed representation 

• A specified action when it is executed; this can include a value (or values) to 
return as well as side-effects 



14.3 The Form of a Menu Item 

Generally speaking, a menu item can take any of several forms, noted in the list 
below. In practice, you find these forms in the specification of particular item types, 
described in the next section. 

a string or a symbol 

The string or symbol is both what is displayed and what is returned. There 
are no side-effects when the item is executed. (Note: nil is not a valid menu 
item.) 

a cons This is like an alist entry. The car is a string or symbol to display and the 
cdr is what to return. The cdr must be atomic to distinguish this case 
from the remaining ones. There are no side-effects. 

a list (name value) 

Another form of alist entry, name is a string or a symbol to display, and 
value is any arbitrary object to return. There are no side-effects when the 
item is executed. 

a list (name type arg optionl argl option2 arg2.„) 

This is the "general list" form, described in more detail below, name is a 
string or a symbol to display, type is a keyword symbol specifying what to do 
when the item is executed, and arg is an argument to it. The options are 
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Label 
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choice boxes 
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Mouse Documentation 



At the bottom of 
the screen 



Figure 2. Components of a menu. 
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keyword symbols specifying additional features desired, and the args following 
them are arguments to those options. 

14.3.1 Types of Menu Items 

Each menu item is an instance of a particular type. In most menus, you may not 
want to explicitly specify the type of the menu item. This is because in simple 
menus all the menu items are of the same type. Your code (which processes the 
selected items) presumably knows this type. 

It is possible to specify the type of the menu items, however. This provides another 
dimension of flexibility in menu design. Since items of different types can be 
intermingled in a single menu, selecting different items can generate a variety of 
interesting effects. For example, some items can return a value, while others can 
generate new menus or perform other computations. 

14.3.2 The "General List" Form of Item 

To specify the type of an item, use the "general list" form of item. 

(name type arg optionl argl option2 arg2 ...) 

As described, an arg (argument) field follows each type specification. The predefined 
types of menu items and the meaning of their arguments are listed here. 

rvalue arg is what to return when the item is executed. There are no side-effects. 
:eval arg is a form to be evaluated. Its value is returned. 

:funcall 

arg is a function of no arguments to be called. Its value is returned. 

:funcall-with-self 

Like the ifuncall item type, :funcall-with-self calls a function. However, the 
specified function is called with one argument: self, that is, the menu itself. 

An example demonstrates its use: 

;;; Specify the item list 

;;; Specify the :funcall-with-self item 
("Option 1" :funcall-with-self do-option-1) 

(defun do-option-1 (menu) 

;; send the :option-1 message 
(send menu ' :option-1)) 

:no-select 

This item cannot be selected. Moving the mouse near it does not cause it to 
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be highlighted. This is useful for putting comments, headings, and blank 
spaces into menus, arg is ignored, but it must be present for syntactic 
consistency. 

:kbd arg is sent to the selected window via the :force-kbd-input message. 

Typically it is either a character code that is to be treated as if it were typed 
in from the keyboard, or a list that is a command to the program. It is 
almost always preferable to use a command menu rather than :kbd menu 
items. See the section "Command Menus", page 229. 

:menu arg is a new menu to choose from; it is sent a : choose message and the 
result is returned. Normally arg would be a momentary menu. If arg is a 
symbol it gets evaluated. 

rbuttons 

arg is a list of three menu items. The item actually chosen (that is, the 
item to be executed) is one of these three, depending on which mouse button 
was clicked. The order in the list is (left middle right). 

:window-op 

arg is a function of one argument. The argument is a list of three elements: 
the window the mouse was in before this menu was exposed and the X and 
Y coordinates of the mouse at that time. For a description of the 
tv:window-hacking-menu-mixin: See the section "Basic and Mixin Pop-up 
and Momentary Menus", page 220. This type is not useful unless the 
tv:window-hacking-menu-mixin is present in the window flavor. 

14.3.3 Menu Item Options 

Menu item options follow the arguments in the "general list" form of item. They 
have two purposes: 

• Specifying the font of a menu item 

• Specifying the mouse line documentation string associated with an item 

The menu item option keywords are as follows: 

:font This keyword is followed by a font or a symbol that is the name of a font. 
The item is displayed in that font instead of the menu's default font. 

:documentation 

This keyword is followed by a string that briefly describes this menu item. 
When the mouse is pointing at this item, so that it is highlighted, the 
documentation string is displayed in the documentation line at the bottom of 
the screen. It is considered good practice to include documentation for all 
menu items. 

An example of the use of menu item options is shown here: 
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("Item 2" rvalue 1.5 : documentation "Costs $1.50" :font fonts :tr10) 



14.4 Choosing and Executing 

After an item has been chosen, it is executed. Executing a menu item does what the 
item type tells it to do. Depending on the type of item being executed, executing 
produces a value, performs a side-effect, or both. 

Execution always takes place in the user process (rather than the mouse process). 
Thus, execution can depend on the special-variable environment and can perform 
actions that take a long time, interact with the user, or depend on being able to use 
the mouse. 

The responsibility for executing the chosen menu item rests with either the system 
or the programmer, depending on how the menu is used. The tv:menu-choose 
function and the rchoose message execute the chosen item and return its value, or 
they return nil if no item was chosen. When using command menus the chosen 
item is returned to the user program. See the section "Command Menus", page 229. 
The user program can execute it by sending the :execute message. See the section 
"Useful tv:menu Messages", page 223. 

The importance of executing menu items depends on the function of the menu. 
Some menus contain items that act as "nouns". The user simply chooses one out of 
a group of similar items. In this case, executing the item serves only to translate 
from the item list. The item list contains the printed representation displayed in the 
menu and the documentation displayed in the mouse documentation line. For this 
kind of item, the rvalue item type is often used. 

Other menus contain items that act more like "verbs". The program operating the 
menu might not be aware of the details of each item; it simply allows the user to 
choose one and then executes it. In this case, most of the complicated behavior is 
within the menu item. Typically, the :eval or rfuncall item type is used. 
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15. The Geometry of a Menu 



A menu has a geometry that controls its size, its shape, and the arrangement of 
displayed choices. The creator of a menu may specify some aspects of the geometry 
explicitly, leaving other aspects to be given by the system according to default 
specifications. 

There are two ways the choices can be displayed. They can be shown in an array 
of rows and columns, or they can be in a "filled" format with as many to a line as 
will reasonably fit. Filled format is specified by giving zero as the number of columns. 

The geometry of a menu is represented by a list of six elements: 

columns 

The number of columns (0 for filled format). 

rows The number of rows. 

inside width 

The inside width of the window, in units of the screen (pixels). If you set 
the size or edges of the window the inside width is remembered here and 
acts as a constraint on the menu afterwards. 

inside height 

The inside height of the window, in pixels. If you set the size or edges of 
the window the inside height is remembered here and acts as a constraint on 
the menu afterwards. 

maximum width 

The maximum width of a window, in pixels. The window system prefers to 
choose a tall skinny shape rather than exceed this limit. 

maximum height 

The maximum height of a window, in pixels. The system prefers to choose a 
short fat shape rather than exceed this limit. If both the maximum width 
and the maximum height are reached, the system displays only some of the 
menu items and enables scrolling to make the rest accessible. 

Values of nil for parts of the geometry can be specified to leave that part 
unconstrained. 



15.1 Geometry Init-plist Options 

The init-plist options listed below initialize the geometry of any menu built on the 
tvrmenu flavor. 
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rgeometry list (for tv:menu) Init Option 

Sets up the complete menu geometry, using a list to specify the columns, 
rows, inside-width, inside-height, max-width, and max-height. See the section 
"The Geometry of a Menu", page 213. 

:rows n-rows (for tvrmenu) Init Option 

Sets the number of rows. 

rcolumns n-columns (for tvrmenu) Init Option 

Sets the number of columns in a menu. 

:fill-p t-or-nil (for tvrmenu) Init Option 

Specifies whether to use filled format or columnar format. 



15.2 Geometry Messages 

The following messages may be sent to any flavor of menu to access and manipulate 
its geometry: 

rgeometry of tv:menu Method 

This message returns a list of six elements, which constitute the menu's 
geometry. These are the menu's default constraints, with nil in unspecified 
positions; contrast this with the :current-geometry message. 

rcurrent-geometry of tv:menu Method 

Returns a list of six elements that constitute the geometry corresponding to 
the actual current state of the menu. This contrasts with the rgeometry 
message, which returns the specified default geometry. Only the maximum 
width and maximum height can be nil. 

:set-geometry &optional columns rows inside-width inside-height Method 

max-width max-height of tvrmenu 
Note that this message takes six arguments rather than a list of six things 
as you might expect. This is because you frequently want to omit most of 
the arguments. The geometry is set from the arguments, which can cause 
the menu to change its shape and redisplay. An argument of nil means to 
make that aspect of the geometry unconstrained. An omitted argument or 
an argument of t means to leave that aspect of the geometry the way it is. 

:fill-p of tvrmenu Method 

:set-fill-p t-or-nil of tvrmenu Method 

Get (:fill-p) or set (:set-fill-p) the menu's fill mode, t is returned from :fill-p 
if the menu displays in filled form rather than columnar form. Thus, use t 
to set the fill characteristic. These messages are a special case of the 
:geometry/:set-geometry messages. 
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Note that the messages :set-default-font and :set-item-list (which do what they 
say) also cause the geometry of a menu to be recomputed. 



15.3 Geometry Example 1: a Multicolumned Menu 

It is not necessary to explicitly specify all six values for the geometry list. In the 
following example, only the columns value is supplied, and a one-column menu is 
specified. The rest of the geometry values are computed by using the column value 
to constrain the system-default settings. 

(setq geometry- list (list 1)) 

Figures 3a and 3b show the result of setting the geometry of a menu first to a one- 
column form (3a), then a multicolumn format (3b, using the three-column code 
example below). In the example, the variable result holds the value of the item 
selected by the mouse. 
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Figure 3. Adjusting a menu's column geometry, (a) One column (b) Three columns 

The code used to generate Figure 3b is next. 
;;; Geometry Example 1 



;;; First element in the geometry list specifies three columns 
(setq geometry- list (list 3)) 
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; ; ; Make the menu 

(setq my-menu (tv: make-window 'tvr momentary-menu 

*:label *(:font fonts:hl12b rstring " Selection") 
': geometry geometry- list 
• : borders 3 
*:item-list '(("First" 

("Second" 

("Third" 

("Fourth" 

("Fifth" 

("Sixth" 

("None" 



rvalue 100) 
rvalue 200) 
rvalue 300) 
rvalue 400) 
rvalue 500) 
rvalue 600) 
rvalue 0)))) 



;;; Expose the window, make a choice, 

;;; and leave the value in the variable "result" 

(setq result (send my-menu ' rchoose)) 



15.4 Geometry Example 2: Retrieving Geometry Information 

Figure 4 is an example of a simple menu from which we would like to retrieve 
geometry information. 



Select Color of Issue 
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Orange x 



Figure 4. Simple menu from which geometry information is obtained. 



The code that produced Figure 4 uses the tcurrent-geometry message, which 
retrieves a description of a menu's geometry. Border and font specifications are used 
to customize the menu. (A list of the loaded screen fonts is accessible by using List 
Fonts (n-X) in the Zmacs editor.) 
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;;; Menu Geometry Example 2 

;;; z is an instance of a momentary window created 

;;; by the make-window function 

(setq z (tv: make-window 'tv: momentary-menu 

' : borders 6 

* : font-map *( fonts rbigfnt fonts :hl12i) 

* : label *(:font fonts :hl12i :string " Select Color of Issue "))) 

;;; item-list is a list of menu items 

(setq item-list '("Blue" "Red'' "Yellow" "Green" "Orange")) 

;;; This sends a message to set up an item list 
(send z * :set-item-list item-list) 

The next expression interrogates the menu and returns a list that describes its 
geometry. The list is returned in geometry-facts. (Nothing in particular is done 
with geometry-facts in this example). 

(setq geometry- facts (send z *: current-geometry)) 

The final expression exposes the menu, allows a choice to be made, and returns the 
selected string in the variable result. 

(setq result (send z ' :choose)) 
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16. Momentary and Pop-up Menus 



A momentary menu appears on the screen with a list of items. The user does not 
have to make a choice, however. By moving the mouse outside the menu, the menu 
is made to disappear. 

By contrast, a pop-up menu forces the user to make a choice. The menu does not 
disappear until an item has been selected. 



16.1 The Standard Momentary Menu Interface 

The standard form of a choice facility provides a simple function-call mechanism for 
invoking it without specifying its details. The standard momentary menu interface 
is based on the function tv:menu-choose. 

tv:menu-choose item-list &optional label near-mode default-item Function 

item-list is a list of menu items. See the section "Types of Menu Items", 
page 210. This function pops up a menu and allows the user to make a 
choice with the mouse. When the choice is made, the menu disappears and 
the chosen item is executed. The value of that item is returned. If the user 
moves the mouse out of the menu and far away, it pops down without 
making any choice and nil is returned. 

label is a string to be displayed at the top of the menu, or nil (the default) 
to specify the absence of a label. 

near-mode specifies where to put the menu on the screen. It defaults to the 
list (:mouse) and must be an acceptable argument to 
tv:expose-window-near. 

default-item is the item over which the mouse should be positioned initially. 
This allows the user to select that item without moving the mouse. If 
default-item is nil or unspecified, the mouse is initially positioned in the 
center of the menu. 



16.2 Standard Momentary Menu Example 

The following code is an example of how to instantiate a simple momentary menu. 
Once the menu pops up, the user can make a choice with the mouse. (Any mouse 
button selects the chosen item.) The item-list is a list of menu items in the 
"general list" form. The price variable is set to the value of the selected item, 
specified in the item list. 
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(setq item- list 
*(("Meat and potatoes" rvalue 3.49 : documentation "Costs $3.49") 
("Fish and chips" rvalue 3.79 .-documentation "Costs $3.79") 
("Hash" rvalue 1.49 r documentation "Costs $1.49") 
("Chicken stew" rvalue 2.99 r documentation "Costs $2.99"))) 

(setq price (tvrmenu-choose item-list "F & T Diner ")) 



16.3 The tv:mouse-y-or-n-p Facility 

One of the simplest choice facilities in the system is based on the tv:menu-choose 
function. This is the tv:mouse-y-or-n-p function, which is useful for quick yes-or-no 
queries in a user interface. 

tv:mouse-y-or-n-p item Function 

Takes an item as its argument and displays it in a one-item menu, item is 
usually a string. If the user clicks on this menu with the mouse button, the 
value of the item is returned. If the user moves the mouse out of the menu, 
nil is returned. 



16.4 Basic and Mix in Pop-up and Momentary Menus 

The basic and mixin flavors for ordinary kinds of menus are explained in this 
section. They cannot be instantiated themselves but they are the building blocks of 
the instantiate menus. 

tv:basic-menu Flavor 

All the other menus in the standard menu facility are built on this flavor. 
The basic menu handles an item list, it remembers the last item selected, 
and it knows about its geometry. See the section "The Geometry of a 
Menu", page 213. 

tv:basic-momentary-menu Flavor 

When this flavor is mixed with a window, it creates a kind of menu that is 
only momentarily on the screen. A :choose operation on a deexposed menu 
of this flavor causes it to position itself where the mouse is and expose itself. 
When the user selects an item in the menu, or alternatively moves the 
mouse far away from the menu, the menu disappears and deactivates. 

tv:window-hacking-menu-mixm Flavor 

This menu flavor mixin provides for the :window-op item type. The 
window that the menu is exposed over is remembered. The remembered 
window is used if an item of type :window-op is selected. See the section 
"Types of Menu Items", page 210. 
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16.5 Instantiate Pop-up and Momentary Menus 

The instantiable menu flavors are listed below, followed by an example of how to 
instantiate one of them. Two of the most important menu flavors are tv:menu and 
tv:momentary-menu, since many other menu flavors are built on them. For a 
diagram of the flavor network on which tvrmenu and tv:momentary-menu are 
built: See the section "The Flavor Network of tv:menu", page 293. For an 
enumeration of many of tvrmenu's init-plist options and messages: See the section 
"Init-plist Options for tv:menu'\ page 295. See the section "Messages Accepted by 
tv:menu", page 299. 

tv:menu Flavor 

This is tv:basic-menu with borders and an optional label on top. By 
default, there is no label, but you can specify one with the rlabel init-plist 
option or the :set-label message, tvrmenu is built on the tv:basic-menu, 
tv:borders-mixin, tv:top-box-label-mixiii, tv:basic-scroll-bar, and 
tv:minimum-window flavors. 

tv:momentary-menu Flavor 

This is built on tv:basic-momentary-menu mixed with tv:menu. See the 
section "The Flavor Network of tv:menu", page 293. 

Momentary menus display a list of items. The user can avoid making a choice 
by moving the mouse outside the menu. In this case, the menu disappears. 

tv:pop-up-menu Flavor 

This menu is a combination of tv:menu and tvttemporary-window-mixin, 
but does not have the automatic expose and deexpose features of 
tv:momentary-menu. See the section "Temporary Windows", page 84. It is 
appropriate to use a pop-up menu rather than a momentary menu when you 
want to pop a menu up and make several choices from it before popping it 
back down. Another use is if you want to force the user to make a choice. 
Moving the mouse outside of the menu boundary does not deexpose the 
menu. 

tv:momentary-window-hacking-menu Flavor 

This is a momentary menu combined with tv:window-hacking-menu- 
mixin. The window that the menu is exposed over is remembered when the 
tchoose message is sent. The remembered window is used if a :window-op 
type item is selected. 

tv:momentary-menu &optional (superior tvtmouse-sheet,) Resource 

This is a resource of momentary menus. tv:menu-choose allocates a 
window from this resource. 
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16.6 Useful tvimenu Init-plist Options 

This is a list of some of the most frequently used init-plist options for the tvrmenu 
flavor and menu flavors built on it, such as tv:momentary-menu and 
tv:pop-up-menu. For a list of more window-related init-plist options associated with 
any flavor built on tv:menu: See the section "Init-plist Options for tvrmenu", page 
295. 

rborders argument (for tvrmenu) Init Option 

This option initializes the parameters of the borders. The argument can be 
nil, which specifies no borders, t, which specifies default borders, or it can be 
a specification of a border. The specification indicates which function is used 
to draw the border and how thick the border is, in pixels. 

If the specification is a number y the border is drawn by the default function 
at the specified thickness. The default function is 
tvrdraw-rectangular-border. 

If the specification is a symbol, the border is drawn by the specified function 
at a default thickness. For more details on creating a function: See the 
section "Using the Window System", page 71. 

If the specification is a cons in the form (function . thickness), the borders 
are drawn by the specified function at a specified thickness. 

The specification can also be a list of locations on the screen: (left top right 
bottom). 

:default-font font (for tv:menu) Init Option 

Sets the default font. Items whose font is otherwise unspecified are displayed 
in the default font. 

:font-map list (for tvrmenu) Init Option 

Specifies a list of fonts associated with the window. 

:item-list list (for tv:menu) Init Option 

Specifies the item list associated with a menu. 

:label specification (for tvrmenu) Init Option 

Specifies the menu's label. The specification is usually a list in the following 
form: 

(rstring "Foo" :font font-specification) 

:vsp n-pixels (for tvrmenu) Init Option 

Sets the vertical spacing between lines in the menu. The default is 2 pixels. 

See the section "Geometry Init-plist Options", page 213. 
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16.7 Useful tv:menu Messages 

This is a list of some useful window and menu-related messages associated with the 
tv:menu flavor and any flavor built on it. For a list of more window-related 
messages to tv:menu: See the section "Messages Accepted by tvtmenu", page 299. 

:choose of tv:menu Method 

This message exposes the window and allows the user to make a choice with 
the mouse. It sends :execute to the window and performs the action 
specified by the item's type. 

rexecute item of tv:menu Method 

This message extracts the value from a chosen item and returns it, or it 
performs a side-effect, or both. It decides what to return based on the item's 
type. See the section "Types of Menu Items", page 210. 

In a program that uses command menus, the :any-tyi message can return a 
blip containing the menu and an item. The program sends the rexecute 
message to the menu to execute the item. See the section "Command 
Menus", page 229. 

rexecute is sent by the system for other kinds of menus. For example, the 
rchoose message, which returns a value and not an item, uses the '.execute 
message to retrieve the value from the chosen menu item. 

rdeactivate of tv:menu Method 

This message deactivates a window, deexposing it. In momentary menus, it is 
sent when the mouse is moved outside the borders of the menu. 



16.8 tv:momentary-menu Example 1: Simple Momentary Menu 

An example of a simple momentary window with three items in it from which to 
select is shown in Figure 5. 



Select one 

Rontmorillonite 

Hectorite 

Beidellite 



Figure 5. Momentary menu example. 

The code to produce such a menu is given next. (In the example, there are no 
actions specified when an item is selected.) 



224 

Programming the User Interface March 1985 



;;; Momentary Menu Example 1 

;;; z is an instance of a momentary menu created by the 

;;; make-window function 

(setq z (tv: make-window 'tv. momentary-menu 

Mabel '(:string -Select one" :font :fonts:hl12b))) 

;;; item- list is a list of menu items 

(setq item-list '("Montmorillonite" "Hectorite" "Beidellite")) 

;;; This passes a message to set up an item list 
(send z ' :set-item-list item-list) 

;;; The rchoose message exposes the window and allows the mouse 
;;; to select an item, choice holds the result, 
(setq choice (send z 'rchoose)) 



16.9 tv:momentary-menu Example 2: Item List as Init-plist Option 

Another way to set up the item list is to specify it as an init-plist option. 

;;; Example 2 

;;; Shows use of the init-plist to specify items 

(setq z (tv: make-window f tv: momentary-menu 
■•: label " New Selection " 
':item-list '("First" "Second" "Third"))) 

(setq choice (send z 'rchoose)) 



16.10 tv:momentary-menu Example 3: Centered Label and Use of 
General List Items 

In Example 3, two new principles are shown. First, in order to have a centered label 
for the menu, the new flavor momentary-menu-with-centered-label is created. 

Second, the "general list" form of item list is used. See the section "The "General 
List" Form of Item", page 210. This allows your program to invoke an operation or 
return a value when an item is selected. In the example, the variable choice is set 
to nil or one of the numbers 1.0, 2.0, or 3.0, depending upon the action taken by 
the user. 

The :font option keyword specifies the font of the displayed item. 

The :documentation option keyword has the following effect. When an item with 
the documentation keyword is pointed at by the mouse, the specified 
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documentation string appears in the inverse-video mouse documentation line at the 
bottom of the screen. 

; ; ; Example 3 

;;; Shows use of flavor mixing and "general list" menu items 

;;; Define a flavor with the centered-label-mixin 
(def flavor momentary-menu-with-centered- label () 

(tvrcentered-label-mixin tv: momentary-menu)) 

;;; Create an instance of the window 
(setq z (tv: make-window 

'momentary-menu-wi th-centered- 1 abel 
': label "Selection" 

' ritem-list '(("Orange" rvalue 1.0 rfont fonts:tr12b 
: documentation "Select orange.") 
("Red" rvalue 2.0 :font fonts:hl12b 

: documentation "Select red.") 
("Yellow" rvalue 3.0 rfont fontsrprt12b 
r documentation "Select yellow.")))) 

(setq choice (send z ' rchoose)) 



16.11 tv:momentary-menu Example 4: Using the Mouse Buttons 

The general list form can include choices that depend on the three mouse buttons. 
:buttons is a menu itemtype that takes three arguments (left middle right), each of 
which specifies what to do if a particular button is pressed. If any argument to 
:buttons is nil, a click on that button is ignored. See the section "Types of Menu 
Items", page 210. An example demonstrates its use. 

;;; Example 4, shows the use of different mouse buttons 

;;; Specify the item list 
(setq button- list 

'(("One Item, Three Ways" 

rbuttons ((1 reval (print "left")) 
(m reval (print "middle")) 
(r reval (print "right"))) 
r documentation 
"Lr Print left, Mr Print middle, Rr Print right"))) 



; ; ; Hake the menu 

(setq menu-1 (tv: make- window 'tvr momentary-menu 

f r label "Test Buttons" 
*r item- list button-list)) 
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;;; Expose the window and choose 
(setq choice (send menu-1 'rchoose)) 



16.12 tv:pop-up-menu Example 

Since a pop-up menu does not operate as automatically as a momentary menu, it 
requires a slightly different treatment. The normal mode of operation is to allow 
rchoose to activate and expose it, and then send it a rdeactivate message when 
done. This does not "destroy" the menu, it just makes sure it does not appear on 
the screen. 

Figure 6 shows a simple example of a pop-up menu. We use the "general list" form 
of item to invoke a function that exposes a second menu and stores the results of 
the two selections in the variables drink and price. 



Juice selection 



Grapefruit 
Orange 

None 



El 



hat size please? 
Dinky 
targel X 
Jumbo 

None 

hpp\e 



None 



Figure 6. Pop-up menu example. 

The code that generated Figure 6 follows on the next pages. 
;;; Pop-up menu example 

(defvar drink nil) 

(defvar grapefruit "Grapefruit Juice") 
(defvar orange "Orange Juice") 
(defvar apple "Apple Juice") 

;;; This function dispatches according to the kind of 
;;; juice selected, and calls the second menu 
(defun juice (fruit) 
(selectq fruit 

(gr (setq drink grapefruit)) 
(oj (setq drink orange)) 
(ap (setq drink apple))) 
(setq price (send two 'rchoose))) 
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;;; This function handles the no- juice item 
(defun no- juice () 
(setq drink nil)) 

;;; This the first menu, a pop-up menu that allows the user 
; ; ; to select a juice 
(setq one (tv: make-window 

'tv:pop-up-menu 
label "Juice selection" 
: borders 3 

item- list '(("Grapefruit" :eval (juice *gr)) 
("Orange" :eval (juice 'oj)) 
("Apple" :eval (juice *ap)) 
("None" rfuncall no-juice)))) 

;;; This is the second menu, a momentary menu that allows the user 
; ; ; to select a size of drink 
(setq two (tv: make-window 

*tv: momentary-menu 

': label "What size please?" 

• : borders 3 

* :i tern- list 

'(("Dinky" .-value .5 
: documentation "Smallest size costs 50 cents.") 
("Large" rvalue 1.0 

: documentation "Actually medium size, costs $1.") 
("Jumbo" rvalue 1 .5 
: documentation "Big, costs $1.50.") 
("None" rvalue 
r documentation "Cheapest selection by far.")))) 

;;; Operate the menu; explicit exposing and 

;;; deactivating are necessary for pop-up menus 

(defun operate () 

(send one * rexpose-near ' (rmouse)) 

(send one ' rchoose) 

(send one * .-deactivate)) 

;;; Invoke the juice selection menu 
(operate) 



Another way to implement this example would have been to use the :menu item 
type to invoke the second menu. See the section "Types of Menu Items", page 210. 
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17. Command Menus 



Command menus are used when a menu does not stand alone but is part of a frame 
of several window panes, which can include other menus. The entire frame is 
controlled by a single process; each frame sends commands (or blips) to the 
controlling process from a menu. 

In order to understand the operation of a command menu, it is necessary to 
understand the difference between a menu item and a menu item's value. 



17.1 Menu Items and Menu Values 

A menu item consists of a list supplied by the programmer in the item list of a 
menu specification. In most menus, your program rarely receives menu items back 
from the window system; usually the values of the items are returned. There are 
two exceptions to this situation: 

• Certain messages deal explicitly with items, such as the :item-list message, 
which returns the list of items associated with a menu. 

• In command menus, your program receives a command (or blip) back from the 
window system. The blip contains an entire item as well as other information 
(explained in the next section). You send the texecute message to the menu 
to extract the item's value and perform side-effects. 



17.2 Command Blips 

Since the :choose message (which gets a value and not an item) does not operate 
on a command menu, the command is sent to the user process through an I/O 
buffer associated with the menu. (Many windows have an I/O buffer associated with 
them. See the section "Overview of Window Flavors and Messages", page 103.) 
Your controlling process can be looking in its I/O buffer for commands from several 
windows as well as for keyboard input. 

The command chosen by the user is sent to the I/O buffer as a list in the following 
form: 

(:menu chosen-item button-mask window) 

Note: The button-mask is a bit mask with a bit for each button on the mouse. 
This provides the option of taking different actions depending on which mouse 
button was pressed. The bit assignments are as follows: 
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1 Left button 

2 Middle button 
4 Right button 



17.3 Responsibilities of Your Program 

Your program is responsible for performing each of the actions that the :choose 
message would normally do, including the following: 

• Deciding where to put the menu. Usually this is specified in the definition of 
the frame, via :panes and rconstraints specifications in a 
tv:bordered-constraint-frame-with-shared-io-buffer flavor. 

• Exposing the menu. Usually the command menu is part of a frame and the 
entire frame is exposed. 

• Receiving a choice from the mouse. This is received via an I/O operation like 
the :any-tyi message. 

• Executing the choice. Example: (send window 'rexecute chosen-item) 

• Deciding whether to deactivate the frame. This is not normally performed on 
an individual command menu pane. 



17.4 Command Menu Mixins 

tv:command-menu-mixin Flavor 

This is the basic mixin version of the command menu flavor. It is not 
instantiate on its own. 

tv:command-menu-abort-on-deexpose-mixin Flavor 

When a command menu built on this flavor receives the tdeexpose message, 
it searches its item list for an item whose displayed representation is [Abort]. 
If such an item is found, a mouse blip is sent to the I/O buffer indicating 
that the [Abort] item was clicked on. See the flavor 
tv:dynamic-pop-up-abort-on-deexpose-command-menu, page 236. 
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17.5 Instantiate Command Menus 

tv.command-menu Flavor 

This is tv:command-menu-mixin mixed with tvrmenu to make it 
instantiate. 

tv:command-menu-pane Flavor 

This version of the command menu flavor is meant to be used within a 
window frame. See the section "Frames", page 175. 



17.6 tv:command-menu Init-plist Options 

:io-buffer buf (for tv:command-menu) Init Option 

The I/O buffer to be used by a command menu is usually specified when it is 
created. It can be shared with the I/O buffer of another window. I/O 
buffers are created with the tvrmake-io-buffer function. 

Note: By making a command-menu to be a pane in a a tv:bordered-constraint-frame- 
with-shared-io-buffer, you are supplied with an I/O buffer automatically. The frame 
puts an :io-buffer option into the init-plist of each pane. See the section "Frames", 
page 175. 



17.7 tv:command-menu Messages 

:io-buffer of tv:command-menu Method 

This message gets the I/O buffer to which a command menu sends a 
command when an item is chosen. 

:set-io-buffer io-buffer of tv:command-menu Method 

This message sets the I/O buffer to which a command-menu sends a 
command when an item is chosen. 



17.8 tv:command-menu Example 

Figure 7 shows a simple command menu. The top pane contains a command menu 
that allows the user to draw an object on the screen. The middle pane is the 
drawing surface. The bottom pane is another command menu that allows the user 
to refresh the drawing surface or exit. 

The Lisp code to produce the window in Figure 7 is shown next. 
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£±rcl<fr. 



Square 





Refresh 



Exit 



Figure 7. Command menu example. 



;;; Define the frame and its panes 
(setq *test- frame* 

(tv: make-window 
* tv : bordered-constrai nt- f rame-wi th-shared- i o-buf f er 
;; Select the graphics pane when it is exposed 
' :selected-pane 'graphics-pane 
;; Specify the panes 
•: panes 
' ( ( 1 ower-menu-pane 

tv: command-menu-pane 

: item-list 

(("Refresh" rvalue : refresh 

: documentation "Refresh graphics pane") 
("Exit" rvalue rexit 
r documentation "Exit this frame."))) 
(graphics-pane tvrwindow r label nil rblinker-p nil) 
(upper-menu-pane 
tvr command-menu-pane 
: item-list 
(("Triangle" rvalue rtriangle 

r documentation "Draw a triangle.") 
("Circle" rvalue rcircle 

r documentation "Draw circle.") 
("Square" rvalue rsquare 
r documentation "Draw square.")))) 
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; ; Specify the size constraints and ordering 

• : constraints 

'((main . ((upper-menu-pane graphics-pane lower-menu-pane) 

;; Big enough for the menu 

((upper-menu-pane :ask :pane-size)) 

;; Big enough for graphics pane 

((graphics-pane :400.)) 

;; Big enough for the menu 

((lower-menu-pane :ask :pane-size) )))))) 

This function accesses the panes and looks for a blip 
in the I/O buffer. It then draws, refreshes the 
graphics pane, or exits 
(defun work () 

; ; Get access to the panes 
(let ((graphics-pane 

(send *test- frame* ':get-pane 'graphics-pane)) 
(upper-menu-pane 

(send *test-frame* ':get-pane 'upper-menu-pane)) 
(lower-menu-pane 

(send *test- frame* ': get-pane 'lower-menu-pane))) 
(send *test-frame* ':expose) 
;; blip holds the list returned by :any-tyi 
(loop as blip = (send graphics-pane ':any-tyi) 
as result- value = 

(cond ((and (listp blip) (eq (car blip) ':menu)) 

(send (fourth blip) 'rexecute (second blip))) 
(t nil)) ;just ignore keyboard input 
do 

;; Check the value and draw the appropriate object 
(selectq result-value 
( -.square 
(send graphics-pane ': draw-rectangle 180. 180. 800. 110.)) 
( :circle 
(send graphics-pane *:draw-filled-in-circle 530. 200. 94.)) 
(•.triangle 
(send graphics-pane ' :draw-regular-polygon 
82. 120. 282. 120. 3)) 
( : refresh 

(send graphics-pane 'rrefresh)) 
(-.exit 
(send *test- frame* ': deactivate) 
(return)))))) 

(work) 
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18. Dynamic Item List Menus 



A dynamic item list menu is a menu in which the items change in between 
exposures. You see an example of a dynamic item list menu when you click on the 
[Select] item on the System menu (Figure 8). At different times, a different item 
list appears, depending upon how many different processes were activated by the 
user. 



Edit: choi4. 


mss /dess/doc/roads/choi 

Converse 

Peek 


ce/ UIXEN: 


Terminal 1 (SUPDUP) — VIXEN on 


CHAOS 




Main Zmail Window 






File System (FS Edit) 






Lisp Listener 1 
Flavor Examiner! 






X 



Figure 8. Select menu, an example of a dynamic item list menu. 

You can add an item to the menu by changing the value of the variable supplied as 
the :item-list-pointer init-plist option. At appropriate times the menu checks to 
see if this variable has been changed. If it has, the menu automatically updates the 
item list. (Do not directly modify the item list yourself, as it is part of the menu.) 
For a description of the times when the menu checks the state of 
:item-list-pointer option, See the section "Messages to Dynamic Menus", page 237. 

The dynamic item list feature is provided only for momentary and pop-up menus; it 
is not available for use in menus within fixed frames. 



18.1 Dynamic Item List Mixins 



tv:abstract-dynamic-item-list-mixin Flavor 

This is a noninstantiable mixin flavor that implements the general notion of 
dynamically changing the item list. It causes the menu's item list to be 
updated at appropriate times. The actual item list is computed via the 
:update-item-list message. 

tv:dynamic-item-list-mixin Flavor 

This is a noninstantiable mixin flavor, built on 
tv:abstract-dynamic-item-list-mixin used as a building block to make 
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instantiable versions listed later. This flavor provides a specific means of 
getting the latest item list, by evaluating a Lisp form, and provides the 
:item-list-pointer instance variable. 

In the operation of this flavor, the old result of evaluating the value of 
:item-list-pointer is saved; if the new result of evaluating the value of 
:item-list-pointer is not the same (compared with the equal function), then 
the item list is considered changed and the menu is updated. 
:item-list-pointer is evaluated when the :choose message is sent. 

tv:dynamic-multicolumn-mixin Flavor 

This is a noninstantiable mixin flavor. It makes a menu have multiple 
"dynamic" columns. Each column comes from a separate item list that is 
recomputed at appropriate times. The instance variable tv:column-spec-list 
is a list of columns. Each column list is in the form: 

(heading item-list-form . options) 

Heading is a string to go at the top of the column, and options are menu 
item options for it (typically a font specification), item-list-form is a form to 
be evaluated (without side-effects) to get the item list for that column. 



18.2 Instantiable Dynamic Item List Menus 

tv:dynamic-momentary-menu Flavor 

This is a momentary menu with the tv:dynamic-item-list-mixin and the 
tv:abstract-dynamic-item-list-mixin. 

tv:dynamic-momentary-window-hacking-menu Flavor 

This is a momentary menu with both the tv:dynamic-item-list-mixin and 
the tv:window-hacking-mixin. 

tv:dynamic-pop-up-menu Flavor 

This is a pop-up menu with the dynamic item-list mixin. 

tv:dynamic-pop-up-command-menu Flavor 

Specifies a command menu with the temporary-menu and dynamic item-list 
mixins. It is mixed in to form the hardcopy menu flavor press:hardcopy- 
dynamic-pop-up-command-menu-with-highlighting. 

tv:dynamic-pop-up-abort-on-deexpose-command-menu Flavor 

This is a command menu with the tv:dynamic-pop-up-command-menu 
and tv:abort-on-deexpose mixins. 
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18.3 Init-plist Option for Dynamic Menus 

:column-spec-list form (for tv:dynamic-multicolumn-mixin) Init Option 

Specified as a list of columns in the form: 

(heading item-list-form . options) 

Heading is a string to go at the top of the column, and options are menu 
item options for it (typically a font specification), item-list-form is a form to 
be evaluated (without side-effects) to get the item list for that column. 

:item-list-pointer form (for tv:dynamic-...-menu) Init Option 

The ellipses in the name (...) indicate that this option works with several 
flavors of dynamic menus. The form is saved and evaluated periodically to 
get the item-list for the menu, form is usually a special variable but any Lisp 
form is valid. The evaluation may occur in any process, so only global 
variables should be accessed. If the result of evaluating form is not equal to 
the item list, the message :set-item-list is sent to the menu to update the 
new list. Note that the Lisp function equal is used for comparison, not eq. 
(Do not directly and destructively modify a menu's item list yourself; the 
system will do this automatically.) 



18.4 Messages to Dynamic Menus 

:update-item-list of tv:dynamic-...-menu Method 

Updates the item list if it needs to change; this message is accepted by 
menus with the dynamic item-list mixin. The :update-item-list message 
sends a :set-item-list if one is necessary. The dynamic menu sends itself 
this message automatically at appropriate times. The appropriate times are 
before :choose, :move-near-window, :center-around, :size, and 
:pane-size messages. 



18.5 Dynamic Menu Example 

A graphic example of a dynamic-momentary-menu is given in Figure 9. The menu is 
shown in its state before updating (a) and after updating (b). This is followed by a 
listing of the code that produces it. 
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Figure 9. Dynamic menu example. 

;;; Dynamic Menu Example 

;;; Set up the initial item list and define the 
;;; dynamic- item- list pointer, 
(defvar pointer 

'("Door Number 1" 

"Door Number 2" 

"Door Number 3")) 

;;; Make the dynamic menu 

(defvar doors (tv: make-window *tv: dynamic-momentary-menu 

iborders 4 

default- font • fonts :tr 12b 
label "CHOICES" 
item-list-pointer 'pointer)) 

;;; Expose the menu, allowing a choice to be made 
(send doors * rchoose) 

(In the example, nothing is being done with the result.) 

Here is an example of dynamically updating the item list. The :update-item-list 
message is sent automatically and transparently by the menu to itself. The user 
does not have to explicitly send it. 

;;; Add entries to the item list 
(setq pointer 

(append pointer (list "Door Number 4" "Door Number 5"))) 

; ; ; Expose the menu with the new choices added 
(send doors ' rchoose) 



18.6 Adding an Item to the System Menu 



Although they are not specifically a part of the dynamic item list facility, two 
functions exist for adding an item (such as the name of a program) to the System 
menu. 
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18.6.1 Adding an Item to the Programs Column 

To add an item to the Programs column of the System menu, use the following 
function: 

tv:add-to-system-menu-programs-column name form Function 

documentation &optional after 
Adds a program to the Programs column of the system menu, name is a 
string, the name to appear in the menu, form is a form to evaluate, in its 
own process, when the program is selected; often this is a call to 
tv:select-or-create-window-of-flavor. documentation is mouse 
documentation for the menu item, after determines the position of the new 
program name in the Programs column: 

nil Bottom of the column 

t Top of the column 

string After the program named string that is now in the menu 

Example: 

(tv:add-to-system-menu-programs-column 
"Concept Editor" 'crl:concept-editor 
"Edit the representation of a concept in the CRL system") 

18.6.2 Adding an Item to the Create Column 

To add an item to the Create menu used in the System Menu and the Screen 
Editor, use the following function: 

tv:add-to-system-menu-create-menu name flavor documentation Function 

&optional after 
Adds an entry to the menu that appears when you click on [Create] in the 
System Menu or in the Edit Screen menu, name is a string, the name of 
the menu item, flavor, a flavor name, is the flavor of window that is created 
when the menu item is selected, documentation is mouse documentation for 
the menu item, after determines where in the [Create] menu the item 
should appear: 

nil Bottom of the menu 

t Top of the menu 

string After the item named string that is now in the menu 
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Example: 

( tv : add- to-system-menu-create-menu 
"Concept Editor" *crl: concept-editor 
"Edit the representation of a concept in the CRL system") 

18.6.3 tv:select-or-create-window-of-flavor Function 

tv:select-or-create-window-of-flavor find-flavor &optional Function 

(create-flavor find-flavor) 
Selects the most recently selected window of flavor find-flavor. If no window 
of that flavor exists, makes a window of flavor create-flavor and selects it. 
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19. Multiple Menus 



Multiple menus allow several items to be selected at a time. The selected items are 
highlighted in inverse video. Clicking the mouse on an item complements its selected 
state. Clicking the default special choice [Do It] associated with a multiple menu 
completes the selection, and returns the result of executing all the highlighted 
choices. The lower portion of Figure 10 is an example of a hardcopy multiple menu 
with several items selected. 
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Figure 10. Hardcopy multiple menu. 



19.1 Multiple Menu Mixins 



These are the noninstantiable flavors that add multiple menu behavior to a window. 

tv:menu-highlighting-mixin Flavor 

This mixin flavor allows some of the menu items to be highlighted with 
inverse video. This is typically used with menus of options, where the 
options currently in effect are highlighted. The menu items corresponding to 
modes are typically set up so that when executed, they adjust the 
highlighting to reflect the enabling or disabling of a mode. 

tv:multiple-menu-mixm Flavor 

This mixin flavor gives a menu the ability to have multiple items "selected". 
Selected items are highlighted with inverse video, using the 
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tv:menu-highlighting-mixm. Clicking on an item merely complements its 
selected state and does not execute it or return from the :choose message. 

Normally (but not in the example above) at the top of the menu, in italics, 
are displayed some "special choices" (for example, [Do It] or [Abort]) that 
cannot be highlighted. Clicking on one of these behaves the same as clicking 
on an item of an ordinary menu. 

By default, the only special choice is [Do It], which returns (from the 
:choose message) a list of the results of executing all the highlighted choices 
(that is, the result of the rhighlighted-values message). You can define 
your own special choices with the rspecial-choices init-plist option, or get rid 
of them entirely by giving nil as the argument to this option. 



19.2 Instantiate Multiple Menus 

tv:multiple-menu Flavor 

This instantiate menu flavor is a combination of tv:multiple-menu-mixin 
with tv:menu. It must be explicitly deactivated by the user program. 

tv:momentary-multiple-menu Flavor 

This instantiate flavor is built on tv:multiple-menu-mixin and tv:menu- 
highlighting-mixin with tv:momentary-menu.The menu is exposed near the 
mouse, and like any momentary menu, the menu disappears once the user 
has made a choice. 



19.3 tv:multiple-menu-mixin Init-plist Options 

:highlighted-items items (for tv:menu-highlighting-mixin) Init Option 

When a menu with the menu-highlighting mixin is created, the list of items 
to be initially highlighted may be specified. The default is nil. 

rspecial-choices choice-list (for tv:multiple-menu-mixin) Init Option 

Each element of choice-list specifies a menu item for a multiple menu. 
These are the items that behave like normal menu items; the items from the 
:item-list init option behave as on/off switches as described above. An 
element of choice-list may be any form of menu item. 
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19.4 tv:multiple-menu-mixin Messages 

rhighlighted-items of tv:menu-highlighting-mixin 

Get the list of highlighted items. 

:set-highlighted-items list of tv:menu-highlighting-mixin 

Set the list of items to be highlighted. 

:add-highlighted-item item of tv:menu-highlighting-mixin 
Add an item to the list of items to be highlighted. 

:remove-highlighted-item item of tv:menu-highlighting-mixin 

Remove an item from the list of highlighted items. 

rhighlighted-values of tv:menu-highlighting-mixin 
:set-highlighted-values list of tv:rnenu-highlighting-mixin 
:add-highlighted-value value of tv:menu-highlighting-mixin 



Method 

Method 

Method 

Method 

Method 
Method 
Method 



:remove-highlighted-value value of tv:menu-highlighting-mixin Method 

These messages are similar to the preceding four, except that instead of 
referring to items directly you refer to their values, that is, the result of 
executing them. For instance, if your item-list is an association list, with 
elements (string . symbol), these messages use symbol. This only works for 
menu items that can be executed without side-effects, not, for example, the 
:eval and rfuncall kinds. 



19.5 tv:momentary-multiple-menu Example 



A simple example of defining a momentary multiple menu is given in Figure 11. The 
example of a Thai restaurant is used to illustrate the situation where more than one 
choice is appropriate. 

The Lisp code used to generate Figure 11 is given in this example of setting up and 
using a multiple menu. The variable selections is used to contain the selected 
items. 
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Figure 11. Momentary multiple menu. 



Multiple Menu Example 

Set up the item list. Each of the dishes has a name and 
a number. When selected, the names are highlighted, 
(setq items '(("Yum Hed Koong" 1) 

("Nur Pud Nor-mai" 2) 

("Nur Pud Pek" 3) 

("Nam Sod" 4) 

("Gai Pud Gra-prao" 4) 

("PI a Preow Warn" 5) 

("Pud Thai" 6))) 



;;; This handles the "Do It" special item 
(defun do- it () 

;; Get the names of the selected dishes 
(setq names 

(mapcar *car (send Thai-menu * :highlighted-items))) 
;; Get the numbers of the selected dishes 
(setq selections 

(send Thai-menu ' :highlighted-values))) 

;;; This handles the "None" special item 
(defun none () 

(send Thai-menu ': set-high lighted- items nil) 

(setq selections nil) 

(setq names nil)) 
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; ;; This handles the "All" special item 
(defun all () 

;; Make all the items selected 

(send Thai-menu' :set-highlighted-i terns items) 

; ; Get the names of the selected dishes 

(setq names (mapcar 'car (send Thai -menu '-.high lighted- items))) 

;; Get the numbers of the selected dishes 

(setq selections (send Thai-menu 'rhighlighted-values))) 

;;; This sets up the special choice list. 

;;; When one of these is selected, the menu exits. 

(setq choices '(("Do it" :eval (do-it)) 

("None" :eval (none)) 

("All" :eval (all)))) 

;;; This instantiates the menu 
(setq Thai -menu (tv: make-window 

'tv:momentary-multi pie-menu 

' :i tern- list items 

' rspecial-choices choices)) 

;;; This exposes the menu, allowing choices to be made, 
(send Thai-menu 'rchoose) 
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20. The Multiple Menu Choose Facility 



The multiple menu choose facility provides menus with several columns. The user 
may choose one item from each column. The selected choice in each column is 
highlighted with inverse video. At the bottom of the leftmost two columns are two 
special choices, in italics. The [Do It] choice selects all the highlighted choices. 
[Abort] deactivates the menu with no further action. 

An example of the multiple menu choose facility can be displayed by clicking right on 
the [Reply] item in the main Zmail window, as in Figure 12 below. 
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Figure 12. Multiple menu choose facility in Zmail. 

Menus of this type are operated by the :multiple-choose message rather than the 
rchoose message. 



20.1 The Standard Multiple Menu Choose Function 

This function provides all the default values necessary for a simple multiple-menu- 
choose menu. 

tv:multiple-menu-choose item-list defaults &optional near-mode Function 

item-list is a list of lists of menu items. Each sublist corresponds to a 
column, defaults is a list of menu items, one for each column, which are 
initially highlighted. 

The function pops up a menu and allows the user to make choices with the 
mouse. The special choices [Do It] and [Abort] are supplied automatically. 
The function returns the list of selected menu items or nil if the user aborts. 
Note: The tv:multiple-menu-choose function executes items when they are 
chosen, not when the [Do It] choice is made. The menu items should not 
have any side-effects when executing. 
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tv:defaulted-multiple-menu-choose item-list defaults &optional Function 

near-mode 
item-list is a list of lists of menu items. Each sublist corresponds to a 
column. 

defaults is a list of menu values, one for each column, which are initially 
highlighted. 

This function is similar to tv:multiple-menu-choose but the defaults 
received by it and the values returned by it are values, not items. 



20.2 tv:multiple-menu-choose Example 

An example of a simple multiple-menu-choose menu is shown in Figure 13. 
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Figure 13. A standard multiple-menu-choose menu. 

The code to produce the menu in Figure 13 follows. 

;;;This sets up the three-row item list 
(setq possibilities 

'((Item-AA Item-AB Item- AC) 

(Item-BA Item-BB Item-BC) 

(Item-CA Item-CB Item-CC))) 

;;; This instantiates the menu 

(setq new-menu (tv:multiple-menu-choose 

possibilities '(Item-AA Item-BA Item-CA))) 

20.3 Multiple Menu Choose Mixin and Resource 

tv:multiple-menu-choose-menu-mixin Flavor 

This is the basic flavor that makes a window exhibit multiple-menu-choose 
behavior. 

tv:pop-up-multiple-menu-choose-resource Resource 

This is a resource of multiple-menu-choose menus. 
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20.4 Instantiate Multiple Menu Choose Flavors 

tv:multiple-menu-choose-menu Flavor 

This is the instantiable version of the multiple-menu-choose flavor, 
constructed by mixing tv:multiple-menu-choose-menu-mixin with 
tvrmenu. It accepts the :multiple-choose message. 

tv:pop-up-multiple-menu-choose-menu Flavor 

This is a combination of tv:multiple-menu-choose-menu-mixin and tv:pop- 
up-menu. The arguments are the same as tv:multiple-menu-choose-menu. 
It accepts the rmultiple-choose message. 



20.5 tv:multiple-menu-choose-menu Example 

Figure 14 shows an example of a momentary-multiple-item-list menu generated using 
the flavor tv:multiple-menu-choose-menu. The figure is followed by the code that 
generated the menu. 
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Figure 14. Momentary multiple-menu-choose menu. 
;;; Mul tiple-menu-choose-menu Example 

;;; Define the item list of lists 
(setq items-3x3 

'((Item-AA Item-AB Item-AC) 

(Item-BA Item-BB Item-BC) 

(Item-CA Item-CB Item-CC))) 

;;; Specify the default, highlighted items 
(setq default-items '(Item-AA Item-BB Item-CC)) 

; ; ; Make the menu 
(setq newer-menu 
(tvrmake-window 

'tvrrnul tiple-menu-choose-menu 

•: label 

'(rfont fonts:hl12b :string "Pick Any Three") 

': borders 2)) 
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;;; Choose an item from each column; resultat holds result 
(setq resultat 

(send newer-menu 

':multiple-choose items-3x3 default- items)) 
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21. The Multiple Choice Facility 



The Multiple Choice facility produces a window containing several items, one per 
text line. For each item, there can be several yes/no choices for the user to make. 
For an example of a multiple-choice window, try selecting the [Kill or Save Buffers] 
operation in the Zmacs editor menu (see Fig. 15). 
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Figure 15. Multiple choice facility in the Zmacs menu. 

Note that the window is arranged in columns, with headings at the top. The 
leftmost column contains the text naming each item. The remaining columns 
contain small boxes (called choice boxes). A "no" box has a blank center, while a 
"yes" box contains an "X". 

Pointing the mouse at a choice box and clicking the left button complements its 
yes/no state. Each choice can be initialized by the program to yes or no as 
appropriate for a default set-up. Note that some items cannot allow some choices, so 
there can be blank places in the array of choice boxes. 

There can be constraints among the choices for an item. For example, if they are 
mutually exclusive then clicking one choice box to "yes" automatically sets the other 
choice boxes on the same line to "no". 

Several parameters are associated with a multiple-choice window: 

• Item-name - a string which is the column heading for the leftmost column. 

• Item-list - a list of representations of items. Each element is a list, 
(item name choices), item is any arbitrary object, name is a string which 
names that object; it is displayed on the left on the line of the display devoted 
to this item, choices is a list of keywords representing the choices the user 
can make for this item. Each element of choices is either a symbol, keyword, 
or a list, (keyword default). If default is present and non-nil, the choice is 
initially "yes"; otherwise it is initially "no". 

• Keyword-alist is a list defining all the choice keywords allowed. Each element 
takes the form (keyword name), keyword is a symbol, the same as in the 
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choices field of an item-list element, name is a string used to name that 
keyword. It is used as the column heading for the associated column of choice 
boxes. 

An element of keyword-alist can have up to four additional list elements, called 
implications. These control what happens to other choices for the same item 
when this choice is selected by the user. Each implication can be nil, meaning 
no implication, a list of choice keywords, or t meaning all other choices. 

The first implication is on-positive; it specifies what other choices are also set 
to "yes" when the user sets this one to "yes." 

The second implication is on-negative; it specifies what other choices are set to 
"no" when the user sets this one to "yes." 

The third and fourth implications are off-positive and off-negative; they take 
effect when the user sets this choice to "no." 

The default implications are nil t nil nil, respectively. In other words the 

default is for the choices to be mutually exclusive. (If the implications 
are not specified, the defaults are rplacd'ed into the keyword-alist 
element by the system.) 

Finishing-choices - the choices displayed in the bottom margin. When users 
click on one of these they are done. The variable 

tv:default-finishing-choices contains a reasonable pair of default finishing 
choices: [Do It] and [Abort]. 



21.1 The Standard Multiple Choice Function 

This function interface to the multiple choice facility provides all the default values 
needed for a simple multiple choice menu. 

tv:multiple-choose item-name item-list keyword-alist &optional Function 

near-mode maxlines 
This function pops up a multiple-choice window and allows the user to make 
choices with the mouse. The dimensions of the window are automatically 
chosen for the best presentation of the specified choices. If there are too 
many choices, scrolling of the window is enabled. 

item-name t item-list, and keyword-alist are as described previously: See the 
section "The Multiple Choice Facility", page 251. The finishing-choices, [Do 
It] and [Abort], are prespecified by the system and cannot be changed by the 
user. 

When the user clicks on one of the two finishing choices in the bottom 
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margin ([Do It] and [Abort]), the window disappears and tv:multiple-choose 
returns. Two cases obtain: 

• If the user finishes by choosing [Abort] the returned value is nil. 

• If the user chooses [Do It], the returned value is a list with one 
element for each item. Each element is a list whose car is the item 
(that arbitrary object which the user passed in the item-list argument) 
and whose cdr is a list of the keywords for the "yes" choices selected 
for that item. 

near-mode tells the window where to pop up. It is a suitable argument for 
tv:expose-window-near. The default is the list (:mouse). maxlines, which 
defaults to twenty, is the maximum number of choices allowed before 
scrolling is used. 



21.2 tvrmultiple-choose Menu Example 

An example of a multiple-choice menu is shown in Fig. 16. 
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Figure 16. Multiple choice menu example. 

The code to produce the multiple-choice menu in Fig. 16 follows. 
;;; Multiple Choice Example 

;;; These are the possible choices the user can make 
(setq choices '(Yes No Explain)) 

(setq selection-item-list 
(list (list 1 " Selection 1" choices) 
(list 2 " Selection 2" choices) 
(list 3 " Selection 3" choices) 
(list 4 " Selection 4" choices) 
(list 5 " Selection 5" choices))) 
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;;; Set the choice boxes 
(setq selection-keyword-alist 

(list '(Yes "Yes, please. ") 

'(No "No, thanks. ") 

'(Explain "What is it? "))) 

; ; ; Expose the menu, 
(setq appetizer-order-list 
(tv:multi pie-choose 

" Today's selections" selection-item-list 

selection-keyword-alist)) 

If a selection is made for each item, an example of the values assigned to the 
variable appetizer-order-list is the following: 

((1 YES) (2 NO) (3 EXPLAIN) (4 NO) (5 NO)) 

If only one selection is made, the values assigned to the appetizer-order-list might 
look like this: 

((1 YES) (2) (3) (4) (5)) 



21.3 The Basic Multiple Choice Flavor 

The default multiple-choice facility described previously is useful for many 
applications, but sometimes more customization is desirable. The basic facilities 
provide many options, allowing you to tailor a multiple-choice menu to specific needs. 

tv:basic-multiple-choice Flavor 

The basic flavor that makes a window implement the multiple-choice facility. 
Like other basic flavors, it is not instantiate on its own but it does commit 
any window that incorporates it to being a multiple-choice window. 
tvrbasic-multiple-choice is built out of tv:text-scroll-window. 



21.4 Instantiate Multiple Choice Menu Flavors 

tv:multiple-choice Flavor 

An instantiate window flavor with the multiple-choice facility in it. It has 
borders and a label area on top which is used for the column headings. 

tv:temporary-multiple-choice-window Flavor 

This is a mixture of tvrmultiple-choice and tvrtemporary-window-mixin. 
Its behavior is that of a multiple-choice window that can be exposed and 
deexposed without deexposing the windows it covers up. 
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tv:temporary-multiple-choice-window &optional (superior Resource 

tvtmouse-sheet,) 

This is a resource of temporary multiple-choice windows. It is used by the 
tv:multiple-choose function. 



21.5 tv:multiple-choice Menu Messages 

The following messages are useful to send to a multiple-choice window. 

rsetup item-name keyword-alist finishing-choices item-list &optional Method 

maxlines of tv:multiple-choice 

This message sets up all the various parameters of the window. Usually one 
sends this message while the window is deexposed. The window decides 
what size it should be and whether all the items will fit or scrolling is 
required, then draws the display into its bit-array. Thus, when the window 
is exposed, the display appears instantaneously. 

For an explanation of item-name, keyword-alist, and finishing-choices, See the 
section "The Multiple Choice Facility", page 251. 

maxlines is the maximum number of lines the window can have; if there are 
more items than this only some of them are displayed and scrolling is 
enabled, maxlines defaults to 20. 

:choose &optional near-mode of tvrmultiple-choice Method 

This message allows menu selection by the mouse. It first moves the window 
to the place specified by near-mode, which defaults to the list (:mouse), (i.e., 
over the current mouse position) and exposes it. Then it waits for the user 
to make a finishing choice and returns the window to its original 
activate/expose status before the :choose operation. When it is sent to a 
multiple-choice menu, this message returns the same value as the function 
tv:multiple-choose. See the section "The Standard Multiple Choice 
Function", page 252. 



21.6 tv:multiple-choice Example 

This example shows how the tvrmultiple-choice flavor can be used to define a 
multiple-choice menu. 

;;; Specify the choice keywords 
(setq choices '(Yes No)) 
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;;; Set the choice boxes 
(setq x-keyword-alist 

(list '(Yes "Yes") 
'(No "No"))) 

;;; Specify the item list 

(setq x-i tern- list 
(list (list "Blue" "Blue" choices) 
(list "Red" "Red" choices) 
(list "Yellow" "Yellow" choices) 
(list "Green" "Green" choices))) 

;;; Make the window 

(setq x (tv: make-window 'tv:multiple-choice)) 

;;; Setup the window 

(send p * rsetup "Select Mode " x-keyword-alist 
tv: default-finishing-choices x-i tern- list) 

;;; Expose the window and make a choice 
(setq result (send p * .-choose)) 
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22. The Choose Variable Values Facility 



The choose-variable-values facility is used throughout the Lisp Machine system 
software. The basic idea of choose-variable-values is to allow the user to interactively 
actfust the value of variables used in a program. 

More specifically, this facility displays a menu of names (standing for Lisp variables), 
followed by colons, and their values. After selecting a value with the left mouse 
button, users can interactively modify the value of the variable. Pressing the middle 
button preloads the input editor with the value of the variable, allowing the user to 
edit it. After the values are modified, the user can exit the menu. 

For an example of a choose-variable-values window, try the [Edit Attributes] option 
of the System menu (see Fig. 17). 



Edit Hindoo attributes of E dit; choi9.mss /dess/doc/roads/cho ice/ VIXEN; 



Current font: MEDFNT 

More processing enabled: Yes No 

Reverse video: YasNo 

Vertical spacing: 2. 

Deexposed typein action: W*k until expose) Notify user 

Deexposed typeout action: Wait untO exposed Notify user Let it happen Signal error Other 

("Other" value of above): MIL 

RLU function for drawing: Ones Zeroes Complement 

ALU function for erasing: Ones Zeroes Complement 

Screen nanager priority: MIL 

Save bits: Yes No 

Label: MIL 

Uidth of borders: 1. 

Uidth of border nargins: 1. 

Do It Q fibort Q 



Figure 17. Choose-variable-values window accessed via the System menu. 

22.1 Variables and Types 

Each variable has a type that limits the values it can assume. The way the value is 
displayed and the way the user enters a new value depend on the type. The types 
fall into two categories: 

Those with a small number of valid values. 

Those with a large or infinite number of valid values. 

The first category displays all the choices, with the current value of the variable in 
boldface. The second category displays the current value until it is selected, at 
which point the value disappears until the user types in a new value. If the user 
rubs out more characters than were typed in, the original value is restored. 
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Note that the type definition mechanism is extensible. You can define new types at 
any time. See the section "Defining Choose Variable Values Types", page 269. 

All variables whose values are to be chosen must be declared special, so that they 
are represented by Lisp symbols and can be accessed non-locally to your program. 
(Note that the compiler automatically declares certain variables to be special. Good 
programming practice mandates that this should be done explicitly by the 
programmer.) 

In most cases, the syntax for input and output is controlled by the binding of the 
Lisp system variables base, ibase, "nopoint, prinlevel, prinlength, package, and 
readtable, as usual. However, the rnumber, :number-or-nil, .-integer, and 
:integer-or-nil types take a :base parameter to specify the base for input and 
output. The default base is decimal. 

Each line of the display is represented by an item, which can be one of the 
following: 

String The string is displayed; strings are useful for putting headings and 

blank separating lines into the display. 

Symbol The symbol is a variable whose type is :sexp; that is, its value can be 

any Lisp object. The name of the variable on the display is simply its 
print-name. 

List in the form: (variable name type args...) 

• variable is the object whose value is being chosen. 

• name is optional; if it is omitted it defaults to the print-name of 
variable. If name is supplied it can be a string, which is 
displayed as the name of the variable, or it can be nil, meaning 
that this line should have no variable name, but only a value. 

• type is an optional keyword giving the type of variable; if omitted 
it defaults to :expression. 

• args are possible additional specifications dependent on type. 

A list is the most general form of item. It is possible to omit name 
and supply type since name is always a string and type is always a 
symbol. For example, both of the following forms are valid item lists: 

(base "Output Base" : integer) 

and 

(base : integer) 

It is also possible to specify a locative in place of a variable. The value 
displayed and modified is the contents of the cell designated by the 
locative. 



259 
March 1985 Window System Choice Facilities 



22.2 Predefined tv:choose-variable-values Variable Types 

The following are the types of variables supported by default, along with any args 
that can be put in the item after the type keyword: 

rboolean 

The value of the variable is either t or nil. The choices are displayed as 
"Yes" for t and "No" for nil. 

:inverted-boolean 

The value of the variable is either t or nil. The choices are displayed as 
"Yes" for nil and "No" for t. 

expression 

The value is any Lisp expression, read with read and printed with prinl. 

:sexp The same as expression. This type is obsolete. 

rprinc The value is any Lisp expression, read with read and printed with princ. 

:eval-form 

The value is the result of evaluating a Lisp form, read and evaluated with 
read-and-eval and printed with prinl. 

rchoose values-list print-function 

The value of the variable must be one of the elements of the list values-list. 
Comparison is by equal rather than eq. All the choices are displayed, with 
the current value in boldface. A new value is entered by pointing to it with 
the mouse and clicking, print-function is the function to print a value; it is 
optional and defaults to princ. 

:assoc values-list print-function 

The displayed object is the car of one of the elements of values-list, while 
the cdr of the element is the value that goes in the variable, print-function 
is the function to print a value; it is optional and defaults to princ. 

rchoose-multiple values-list print-function 

This type takes arguments like the :assoc type, but permits the user to 
choose more than one element in the values list. The variable is set to a list 
of all the values chosen. 

:menu-alist item-list 

The items are specified in an item-list. See the section "Types of Menu 
Items", page 210. The usual menu mechanisms for specifying the string to 
display, the value to return, the function to call, and the mouse 
documentation work with this. :menu-alist is often used for its mouse 
documentation feature. 

•.character 

The value is an integer that is a character code. It is printed as the 
character name (using the ":@C format operator), and it is read as a single 
keystroke. 
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:character-or-nil 

This is an integer like character, but nil is also allowed as the value, nil 
displays as "none" and can be entered by pressing CLEflR-INPUT. 

:stringThis value is a string, printed with princ and read with readline. 

:string-list 

This value is a list of strings, whose printed representation for input and 
output consists of the strings separated by commas and optional spaces. 

:string-or-nil 

This value is a string or nil if the user just presses return, line, or END. 

mumber :base base :or-nil or-nil 

This value is a number. It is printed with prinl and read with 
sys:read-number. If :base is specified, the number is read and printed in 
base base. By default, the number is read and printed in decimal. If :or-nil 
is specified with a value other than nil, a value of nil is accepted when the 
user just presses return, line, or end. nil displays as "none". The default 
for or-nil is nil. 

:number-or-nil :base base 

The same as mumber :base base :or-nil t. This type is obsolete. 

rdecimal-number 

The same as mumber :base 10. This type is obsolete. 

:decimal-number-or-nil 

The same as mumber :base 10. :or-nil t. This type is obsolete. 

dnteger :base base :or-nil or-nil 

This value is an integer. It is printed with prinl and read with 
systread-integer. If :base is specified, the integer is read and printed in 
base base. By default, the integer is read and printed in decimal. If :or-nil 
is specified with a value other than nil, a value of nil is accepted when the 
user just presses RETURN, LINE, or END. nil displays as "none". The default 
for or-nil is nil. 

:date This value is a universal date-time. An ambiguous date is interpreted as 
being in the future. (Compare this with :past-date.) 

:date-or-never 

This value is a universal date-time or nil if the user types "never". An 
ambiguous date is interpreted as being in the future. 

:past-date 

The value is a universal date-time. An ambiguous date is interpreted as 
being in the past. 

:past-date-or-never 

This value is a universal date-time or nil if the user types "never". An 
ambiguous date is interpreted as being in the past. 
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:time-interval-or-never 

The value is an integer representing the number of seconds in a time 
interval, or nil if the user types "never". The interval is read and printed as 
either "never" or alternating numbers and units of time; the units can 
include seconds, minutes, hours, days, weeks, or years. 

:time-interval-60ths 

The value is an integer representing the number of sixtieths of a second in a 
time interval. The interval is read and printed as alternating numbers and 
units of time; the units can include seconds, minutes, hours, days, weeks, or 
years. The smallest unit read or displayed is second. 

:pathname 

The value is a pathname, represented as a string. The pathname read is 
merged with the result of (fsrdefault-pathname) and has a default version 
of :newest. 

:pathname-or-nil 

The value is a pathname, represented as a string, or nil if the user just 
presses RETURN, LINE, or END. The pathname read is merged with the result 
of (fs:default-pathname) and has a default version of :newest. 

:pathname-list 

The value is a list of pathnames, read as a series of pathnames separated by 
commas and optional spaces, and merged with the result of 
(fsrdefault-pathname). The default version is rnewest. The list is printed 
as a series of pathnames separated by commas and spaces. 

:host The value is a network host, read and printed as the name of the host. 

:host-or-local 

The value is a network host. It is read as the name of a host or the string 
"local" to represent the local host. If the host is the local host, it is printed 
as "Local"; otherwise, it is printed as the name of the host. 

:host-list 

The value is a list of network hosts, read as a series of host names separated 
by commas or spaces, and printed as a series of host names separated by 
commas and spaces. 

:pathname-host 

The value is a pathname host, read and printed as the name of the host. 
The name can be "local", "sys", or the name of another logical host as well as 
the name of a physical host. 

:keyword-list 

The value is a list of symbols in the keyword package, read as a series of 
symbol names separated by commas or spaces, and printed as a series of 
symbol names separated by spaces. Symbol names are read and printed 
without package prefixes (that is, not preceded by colons). 
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:font-list 

The value is a list of fonts, read as a series of font names separated by 
commas or spaces, and printed as a series of font names separated by 
commas and spaces. Font names are read and printed without package 
prefixes (that is, not preceded by fonts:). 

A :documentation specification can be inserted where a variable type would 
normally be expected. 

rdocumentation doc type args... 

The actual type of the variable is type, doc is a string that is 
displayed in the mouse documentation line when the mouse is 
pointing at this item. The default, if no documentation is 
supplied using the rdocumentation specification, depends on the 
variable type. It is generally something like "Click left to input a 
new value from the keyboard". 

22.2.1 The Optional Constraint Function 

It sometimes is necessary to ensure that when one variable's value is changed, one 
or more of the others is changed as well. As an init-plist option, a choose-variable- 
values window can have an associated function, which is called whenever a variable's 
value is changed. This function can implement constraints among the variables. 

The constraint function is specified by the rfunction init-plist option. See the 
section "tv:choose-variable-values Options", page 263. It is called with arguments 
window , variable, old-value, and new-value. The function should return nil if just 
the original variable needs to be redisplayed, or t if no redisplay is required; in this 
case it would usually setq several of the variables then send a rrefresh message to 
the window to redisplay everything. 



22.3 The Standard Choose Variable Values Function 

The standard function interface to the choose-variable-values feature chooses the 
dimensions of the window and enables scrolling if there are too many variables to fit 
in the chosen height. 

tv:choose-variable-values variables &rest options Function 

This function exposes a window and displays the values of the specified 
variables, permitting the user to alter them. One or more choice boxes (as in 
the multiple-choice facility) appear in the bottom margin of the window. 
When the user clicks on the [Exit] choice box the window disappears and this 
function returns. The value returned is not meaningful; the result is 
expressed in the values of the variables. 

variables is a list whose elements can be special variables or the more general 
items described above. 
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options is a list of alternating init-plist option keywords and values: See the 
section "tv:choose-variable-values Options", page 263. 



22.4 tv:choose-variable-values Options 

The following option keywords can be specified. 

rlabel string (for tvrchoose-variable-values) Init Option 

The argument is a string that is the label displayed at the top of the 
window. The default is "Choose Variable Values". 

rfunction org (for tvrchoose-variable-values) Init Option 

Specifies the function to be called if the user changes the value of a variable. 
The default is nil (no function). See the section "The Optional Constraint 
Function", page 262. 

:near-mode org (for tvrchoose-variable-values) Init Option 

Specifies where to position the window. The default is the list (:mouse). See 
the section "Input From Windows", page 132. 

rwidth org (for tvrchoose-variable-values) Init Option 

Specifies how wide to make the window. This can be a number of 
characters, or a string (it is made just wide enough to display that string). 
The default is to make it wide enough to display the current values of all the 
variables, provided that is not too wide to fit in the superior window. 

:extra-width arg (for tvrchoose-variable-values) Init Option 

When rwidth is not specified, this specifies the amount of extra space to 
leave after the current value of each variable of the kind that displays its 
current value (rather than a menu of all possible values). This extra space 
allows for changing the value to something bigger. The extra space is 
specified as either a number of characters or a character string. The default 
is ten characters. If rwidth is specified, then rextra-width is ignored. 

rmargin-choices 'list (for tvrchoose-variable-values) Init Option 

The argument is a list of specifications for choice boxes to appear in the 
bottom margin. Each element can be a string, which is the label for the box 
that means "done," or a list containing a label string and a form to be 
evaluated if that choice box is clicked on. Since this form is evaluated in the 
user process it can do such things as alter the values of variables or "throw 
out. With this facility, the default for rmargin-choices is [Exit]. For an 
explanation of margin choices and their use: See the section "The Margin 
Choice Facility", page 289. 
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rsuperior window (for tvrchoose-variable-values) Init Option 

The argument is the window to which the pop-up choose-variable-values 
window should be inferior. The default is the value of tv:mouse-sheet, or 
the superior of w if the :near-mode option is already set to (: window w). 



22.5 tvrchoose-variable-values Examples 

Here are some examples of how to call tvrchoose-variable-values. The simplest 
kind of example is to display some variable names and values and let the user 
change them, as in Fig. 18. To see how it works, point at one of the variables, press 
the left mouse button, and then type in a new value and press Return. Recall that 
*nopoint is a Lisp variable. 



Nunber fornat oaraneters 



BRSE: 18 
IBRSE: 10 
»N0P0INT: NIL 
Exit Q 



Figure 18. Choose-variable-values example 1. 

The Lisp code used to produce Fig. 18 is shown here. 
;;; Choose Variable Values Example 1 

; Invoke the window 

(tv:choose-variable-values '(base ibase *nopoint) 

* : label "Number format parameters") 

The same example can be done with better menu formatting in the next example 
(shown in Fig. 19). 



Nunber fornat oaraneters 



Output Base: 10 
Input Base: 10 
Dec i rial Point: Ve» No 
Exit D 



Figure 19. Choose-variable-values example 2: better formatting. 
The Lisp code used to produce Fig. 19 is given here. 
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;;; Choose Variable Values Example 2 

(tv: choose- vari able-values 

•((base "Output Base" : number) 
(ibase "Input Base" :number) 
(*nopoint "Decimal Point" 

:assoc (("Yes" . nil) 
("No" . t)))) 
• : label "Number format parameters") 

If we had not wanted to reverse the sense of t and nil the entry for *nopoint 
would have been the following: 

(*nopoint "No Decimal Point" :boolean) 

If we wanted to use the name of the variable as the menu item, rather than 
spelling it out, we could have used the following expression: 

(*nopoint :boo1ean) 

As another example, we consider shopping for groceries via Lisp Machine. We have 
variables fish, crustaceans, seafood-specialties, lettuce, and apples. Many 
stores accept coupons for discounts on purchases, so the Coupon-value variable (a 
floating-point number) allows users to enter a dollar value representing the value of 
the coupons they are redeeming. 

As mentioned, clicking [Middle] on the mouse puts the variable in the input editor, 
allowing you to make changes in it. In Fig. 20 we display this situation and allow it 
to be modified, using several different kinds of items: 



Today's Food Selections 



FISH STORE 

Fish: Salnon 

Shellfish: Clans 

Other Seafood: F1y1ng-f1sh roe 

PRODUCE STORE 

Lettuce: Boston Rod Icabarg 

Apples: Macintosh Jonathan Pippin 

VALUE OF YOUR COUPONS 
Coupons: 0. 

a 



Exit 



Figure 20. Choose-variable-values window: grocery store example. 

The Lisp code used to produce Fig. 20 is provided next. Each "STORE" in the 
example is implemented with a different variation of the choose variable value 
facility. Note the use of strings to provide labels for the sections, and null strings to 
separate the sections with blank lines. 
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;;; Choose Variable Values Example 3 

;;; Set up the variables 

(setq fish '( "Salmon")) 

(setq crustaceans '("Clams")) 

(setq seafood-specialties '("Flying-fish roe")) 

(setq lettuce "Boston") 

(setq apples "Pippin") 

(setq Coupon-value 0) 

(setq result (tvrchoose-variable-values 
'("FISH STORE" 
(fish "Fish" :string-list) 
(crustaceans "Shellfish" :string-list) 
(seafood-specialties "Other Seafood" :string-list) 

II M 

"PRODUCE STORE" 

(lettuce "Lettuce" : choose ("Boston" "Red" "Iceberg")) 

(apples "Apples" rchoose ("Macintosh" "Jonathan" "Pippin")) 

II H 

"VALUE OF YOUR COUPONS" 
(Coupon-value "Coupons" 
: documentation 

"Click left to enter the value of your coupons." 

: number)) 
• : label "Today's Food Selections")) 



22.6 The User Option Facility 

The user option facility provides a simple window interface that allows you to set 
parameter options to your programs. The user option facility is based on the choose- 
variable-values facility. 

A typical use would be in a program that requires several variables to be set before 
it is run. In a conventional system, a standard way to alter these values would be to 
alter the code, recompile the program, and then run it. By contrast, the user option 
facility generates a window with the names and default values of the variables. This 
gives you the option of resetting these variables before execution of the program. 
When the window is exited, the rest of the program runs. 

For an example of a user option window, type the following function at a Lisp 
Listener window: 

(choose-user-options zwei :*zmail-user-option-alist*) 

The choose-user-options function is also used by the Zmail Profile mode, and 
elsewhere throughout the system. 

Special forms are provided for defining options, and the choose-user-options 
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function exists for putting all the options into a choose-variable-values window so 
that the user can alter them. In addition, the current state of the options can be 
written into an initialization file, or all the options can be set to their default initial 
values. 

22.6.1 Functions for Defining User Option Variables 

define-user-option-alist name [constructor] Special Form 

(define-user-option-alist name) defines name to be a global variable whose 
value is a "user option alist", something which may be used by the other 
functions below. This alist keeps track of all of the option variables for a 
particular program. 

(define-user-option-alist name constructor) also specifies the name of a 
constructor macro to be defined, which provides a slightly different way of 
defining an option variable from define-user-option. The form 
(constructor option default type name) defines an option in this user-option- 
alist. The arguments are the same as to define-user-option. 

define-user-option (option alist) default [type] [name] Special Form 

(define-user-option (option alist) default type name) defines the special 
variable option to be an option in the alist, which must have been previously 
defined with define-user-option-alist. The variable is declared and 
initialized via (defvar option default). The value of the form default is 
remembered so that the variable can be reset back to it later. 

type is the type of the variable for purposes of the choose-variable-values 
facility. It is optional and defaults to :sexp. 

name is the name of the variable to be displayed in the choose-variable-values 
window. It is optional and defaults to a string that is the print-name of the 
variable except with hyphens changed to spaces and each word changed from 
all-upper-case to first-letter-capitalized. If the first and last characters of the 
print-name are asterisks, they are removed. For example, the default name 
for so:*sunny-side-up* would be "Sunny Side Up". 

22.6.2 Functions for Altering User Option Variables 

choose-user-options alist &rest options Function 

This function displays the values of the option variables in alist to the user 
and allows them to be altered. The options are passed along to 
tv:choose-variable-values. 

reset-user-options alist Function 

This function resets each of the option variables in alist to its default initial 
value. 
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write-user-options alist stream Function 

This function specifies that for each option variable in alist whose current 
value is not equal to its default initial value, a form is printed to stream 
which sets the variable to its current value. The form uses login-setq so it 
is appropriate for putting into an initialization file. 



22.7 User Options Example 

Fig. 21 is an example of a user option window that sets three variables of a simple 
graphics program. 



Ihoose Variable Values 



Density: 180. 
Range: 768. 
ALU Function: 6. 
Exit □ 



Figure 21. User options window example. 

The Lisp code used to produce Fig. 21 is shown between the asterisk-marked (****) 
lines. The rest of the code generates the graphics. 

;;; User Option Example 

;;; This names the user option alist 
(define-user-option-alist options) 

;;; These expressions set of the options 
(define-user-option (alu-function options) 

tv:alu-ior : decimal -number "ALU Function") 
(define-user-option (range options) 768. :decimal -number "Range") 
(define-user-option (density options) 100. rdecimal -number "Density") 

;;; Expose the choose-option window 
(choose-user-options options) 
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;;; This is a random line-drawing function 
(defun image (alu-function range density) 
(setq x (tv: make-window *tv: window)) 
;; Temporarily select a window; the arguments 
;; are the window x and the final action on it 
(tv:window-call (x rdeactivate) 
(setq n range) 
(loop for i below density do 

(send x ' :draw-lines alu-function 

(random n) (random n) (random n) (random n) 
(random n) (random n) (random n) (random n)) 
(send x * :draw-circle 

(random n) (random n) (random n))) 
(send x * :tyi))) 

; ; ; Draw the image 

(image alu-function range density) 



22.8 Defining Choose Variable Values Types 

The standard choose-variable-values facility supplies programmers with a range of 
predefined types. See the section "Predefined tv:choose-variable-values Variable 
Types", page 259. However, this list is extensible through two mechanisms: 

1. Adding a type keyword property to a new type name 

2. Adding a type decoding method 

22.8.1 Adding a Type Keyword Property 

The basic type definition mechanism is simple: put a 

tvrchoose-variable-values-keyword property on the type name. In the following 
example, the new type is called new-type, the property value is type-list, and the 
property name is tv:choose-variable-values-keyword 

(defprop new-type type-list tvrchoose-variable-values-keyword) 

For a discussion of the contents of type-list: See the section "Elements of the 
tv:choose-variable-values-keyword Property", page 270. See the section "Type 
Decoding Message", page 270. 

22.8.2 Adding a Type Decoding Method 

The second way to extend the range of standard types is to define a new flavor of 
choose-variable-values window and give it a :decode-variable-type method 
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~ circumventing the use of the standard variable types. This method must be 
careful to implement the :documentation keyword, which can appear in an item 
where a variable type would normally appear. 



22.9 Type Decoding Message 

:decode-variable-type kwd-and-args of Method 

tv:basic-choose-variable-values 

The system sends this message to a choose-variable-values window when it 
needs to understand an item, kwd-and-args is a list whose car is the 
keyword for the item and whose remaining elements, if any, are the 
arguments to that keyword. Six values are returned. The default method 
for :decode-variable-type looks for two properties on the keyword's 
property list: 

• tv:choose-variable-values-keyword - The value of this property is a 
list of six values: See the section "Elements of the 
tv:choose-variable-values-keyword Property", page 270. 
Unnecessary values of nil may be omitted at the end. 

• tv:choose-variable-values-keyword-function ~ The value of this 
property is a function that is called with one argument, kwd-and-args. 
The function must return the six values. 

22.9.1 Elements of the tv:choose-variable-values-keyword Property 

The six elements of the tvrchoose-variable-values-keyword property are listed 
below. Note that if the specified list is shorter than six elements, the others default 
to nil. 

print-function 

A function of two arguments, object and stream, to be used to print the 
value, prinl is acceptable. 

read-function 

A function of one argument, a stream, to be used to read a new value, read 
is acceptable. If nil is specified, there is no read-function and instead new 
values are specified by pointing at one choice from a list. If the read-function 
is a symbol, it is called inside an input editor, and over-rubout automatically 
leaves the variable with its original value. If read-function is a list, its car is 
the function, and it is called directly rather than inside an input editor. 

choices A list of the choices to be printed, or nil if just the current value is to be 
printed. 
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print-translate 

If there are choices, and this function is supplied non-nil, it is given an 
element of the choice list and must return the value to be printed (for 
example, car for :assoc type items). 

value-translate 

If there are choices, and this function is supplied non-nil, it is given an 
element of the choice list and must return the value to be stored in the 
variable (for example, cdr for :assoc type items). 

documentation 

A string to display in the mouse documentation line when the mouse is 
pointing at this item. This string should tell the user that clicking the 
mouse changes the value of this variable, and any special information (for 
example, that the value must be a number). 

Alternatively, the documentation element can be a symbol that is the name 
of a function. It is called with one argument, which is the current element 
of choices or the current value of the variable if choices is nil. It should 
return a documentation string or nil if the default documentation is desired. 
This can be useful when you want to document the meaning of a particular 
choice, rather than simply saying that clicking on this choice selects it. 

Note that the function should return a constant string, rather than building 
one with format or other string operations. This is because it will be called 
over and over as long as the mouse is pointing at an item of this type. (The 
function is called by the mouse documentation line updating in the scheduler, 
not in the user process.) 



22.10 tv:choose-variable-va!ues Type Definition Example 

;;; Defining a Choose Variable Values Type Example 
;;; Adding the type keyword property 

(defvar candidate-! nil) 
(defvar candidate-2 nil) 
(defvar candidate-3 nil) 

;;; Set up the type list 

(setq type-list 'Cprinc nil ("Yes" "No" "Abstain") nil nil nil)) 

;;; Put the type- list value on the 

;;; tv.choose-variable-values-keyword property 

(putprop * my type type- list 

' tv: choose- vari abl e-val ues- keyword) 
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;;; Use the newly created type 
( tv: choose- vari abl e- val ues 
•((candidate-1 M John Q. Public " mytype) 
(candidate-2 " Jane Doe H mytype) 
(candidate-3 " John Blevins " mytype)) 
' zlabel "*** Select One Candidate ***") 



22.11 Defining a Choose Variable Values Window 

Up to this point, an easy-to-use but limited form of the choose-variable-values facility 
has been discussed, namely, the standard tv:choose-variable-values function. 

In order to create a new flavor of window with choose-variable-values behavior, the 
basic and instantiable choose-variable-values window flavors are needed. These are 
described in this section. The basic flavor requires more parameter specifications 
from the programmer, but it is also the most flexible. The use of choose-variable- 
values windows as panes in a frame and as pop-up windows is also discussed. 



22.12 The Basic Choose Variable Values Flavor 

tv:basic-choose-variable-values Flavor 

This is the basic flavor which makes a window implement the choose- 
variable-values facility. It is built out of tv:text-scroll-window. There are 
two ways to use this. In the first way, the programmer creates a window 
giving all of the parameters in the init-plist. In the second way one can 
create a window without specifying the parameters, then send the rsetup 
message to start the display. 

22.12.1 Instantiable Choose Variable Values Flavors 

tv:choose-variable-values-window Flavor 

This is a choose-variable-values window with a reasonable set of features, 
including borders, a label at the top, stream input/output, the ability to be 
scrolled if there are too many variables to fit in the window, and the ability 
to have choice boxes in the bottom margin. 

tv:choose-variable-values-pane Flavor 

This is a tv:choose-variable-values-window that can be a pane of a 
constraint-frame. For more on constraint frames: See the section "Specifying 
Panes and Constraints", page 179. It does not change its size automatically; 
the size is assumed to be controlled by the superior. 
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tv:temporary-choose-variable-values-window Flavor 

This is a tv:choose-variable-values-window that is exposed temporarily. 
For an explanation of temporary windows: See the section "Temporary 
Windows", page 84. 

22.12.2 I/O Buffers for Choose Variable Values Windows 

I/O buffers can be associated with choose-variable-values windows. See the section 
"Menu Items and Menu Values", page 229. A choose-variable-values window has an 
I/O buffer, which the window uses to send commands (also known as blips) back to 
its controlling process. As usual these commands are lists, to distinguish them from 
keyboard characters that are numbers. If all panes send commands to the same I/O 
buffer, then when one of these commands arrives it can be processed in the 
appropriate pane. At the same time, the controlling process can be looking in the 
I/O buffer for other commands from other panes and for input from the keyboard. 
A choose-variable-values window uses the same I/O buffer to read a new value from 
the keyboard as it uses to send blips to the controlling process. 

The following I/O buffer commands (blips) are sent by the choose-variable-values 
window to the user process. 

(:variable-choice window item value line-number) 

This indicates that the user clicked on the value of a variable, expressing a 
desire to change it. window is the choose-variable-values window instance, 
item is the complete item specification, value is the value that was clicked on, 
and line-number is the line on which the item appears in the menu. The 
lines are numbered starting at 0. 

(:choice-box window box) 

This indicates that the user clicked on one of the choice boxes in the bottom 
margin, window is the window instance, and box is the choice box 
specification. 

The following sequence of events is a typical model for implementing a choose- 
variable-values window. 

1. Set up and expose the window. 

2. Loop within an :any-tyi, or tv:io-buffer-get loop, checking to see if a 
variable-choice or a choice-box selection has been made. 

3. If a choice-box selection has been made, your "choice-box handler" routine is 
called. This routine returns the choice-box descriptor. If the choice-box was an 
[Abort] item, your process typically sends the window the deactivate 
message. 
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tvrchoose-variable-values-process-message window command Function 

This function implements the proper response to the above commands. It 
should be called in the process and stack-group in which the variables being 
chosen are bound. The function returns t if the command indicates that the 
choice operation is "done", otherwise it performs the appropriate special action 
and returns nil. If command is a character, it is ignored unless it is 
#\refresh, in which case the choose-variable-values window is refreshed. 

tv:temporary-choose-variable-values-window &optional (superior Resource 

tvrmouse-sheetj 
A resource of windows, from which tv:choose-variable-values gets a 
window to use. 



22.13 tv:basic-choose-variable-values Init-plist Options 

The following init-plist options are relevant to choose-variable-values windows. Note 
that if no dimensions are specified in the init-plist, the width and height are 
automatically chosen according to the other init-plist parameters. The height is 
dictated by the number of elements in the item-list. Specifying a height in the init- 
plist, using any of the standard dimension-specifying init-plist options, overrides the 
automatic choice of height. Note: the :stack-group option is required, unless the 
rsetup message is used to initialize the window. See the section 
"tvrchoose-variable-values-window Messages", page 275. 

:function function (for tvrbasic-choose-variable-values) Init Option 

Specifies the function called when the value of a variable is changed. See the 
section "The Optional Constraint Function", page 262. The default is nil (no 
function). 

:variables item-list (for tvrbasic-choose-variable-values) Init Option 

Specifies the list of variables whose values are to be chosen. These can be 
either symbols that are variables, or the more general items defined 
previously. See the section "Variables and Types", page 257. 

:stack-group sg (for tv:basic-choose-variable-values) Init Option 

This option specifies the stack group in which the variables whose values are 
to be chosen are bound. The window needs to know this so that it can get 
the values while running in another process, for instance the mouse process, 
in order to update the window display when it is refreshed or scrolled. This 
option is required, unless you use the rsetup message. 

:name-font font (for tv:basic-choose-variable-values) Init Option 

This specifies the font in which names of variables are displayed. The 
default is the system default font. 



275 
March 1985 Window System Choice Facilities 



:value-font font (for tv:basic-choose-variable-values) Init Option 

This is the font in which values of variables are displayed. The default is the 
system default font. 

:string-font font (for tv:basic-choose-variable-values) Init Option 

This is the font in which items that are just strings (typically heading lines) 
are displayed. The default is the system default font. 

:unselected-choice-font font (for Init Option 

tv:basic-choose-variable-values) 

This option determines the font in which choices for a value, other than the 
current value, are displayed. The default is a small distinctive font. 

:selected-choice-font font (for tv:basic-choose-variable-values) Init Option 
This specifies the font in which the current value of a variable is displayed, 
when there is a finite set of choices. This should be a bold-face version of 
the preceding font. The default is the bold-face version of the default 
unselected-choice font. 

rmargin-choices choice-list (for Init Option 

tv:choose-variable-values- window) 

The default is a single choice box, labelled [Done]. For an explanation of the 
choice-box descriptors: See the section "The Margin Choice Facility", page 
289. Note that specifying nil for this option suppresses the margin-choices 
entirely. 

:io-buffer buf (for tvrchoose-variable-values-window) Init Option 

This specifies the I/O buffer to be used. The buffer can be associated with 
another window or it can be explicitly created for this window with the 
tv:make-io-buffer function. The I/O buffer is used both for reading 
keyboard input (new values) and for sending blips to the controlling process. 



22.14 tv:choose-variable-values-window Messages 

The following messages are useful to send to a choose-variable-values window. 

rsetup items label function margin-choices of Method 

tvrchoose-variable-values-window 

This changes the list of items (variables), the window label, the constraint 
function, and the choices in the bottom margin and sets up the display. 
This message remembers the current stack-group as the stack-group in which 
the variables are bound. If the window is not exposed this chooses a good 
size for it. 
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:set-variables item-list &optional dont-set-height of Method 

tvrchoose-variable-values-window 

This changes the list of items (variables) and redisplays. Unless 
dont-set-height is supplied non-nil, the height of the window is adjusted 
according to the number of lines required. If more than 25. lines would be 
required, 25. lines are used and scrolling is enabled. The rsetup message 
uses :set-variables to do part of its work. 

:appropriate-width &optional extra-space of Method 

tv:choose-variable-values- window 

This returns the inside-width appropriate for this window to accommodate 
the current set of variables and their current values. Send this message 
after a :setup and before a :expose, and use the result to send an 
:acUust-geometry-for-new-variables message. The returned width is not 
larger than the maximum that fits inside the superior. 

If extra-space is supplied, it specifies the amount of extra space to leave after 
the current value of each variable of the kind that displays its current value 
(rather than a menu of all possible values). This extra space allows for 
changing the value to something bigger. The extra space is specified as 
either a number of characters or a character string. The default is to leave 
no extra space. 

:actfiist-geometry-for-new-variables width of Method 

tv:choose-variable-values-window 

The variable width is specified as nil if the size is not to be adjusted, 
otherwise the inside-width and height are also adjusted. The 
:acyust-geometry-for-new-variables message is normally sent after sending 
a :setup message. (It is not necessary to send it after a :set-variables 
message.) 

rredisplay-variable variable of Method 

tv:choose-variable-values-window 

This redisplays just the value of the specified variable. 



22.15 tvrchoose-variable-values-window Example 

As we have discussed, in the simplest mode of operation, the 
tv:choose-variable-values function takes care of creating the window and 
establishes all necessary communication with it. When you make a choose-variable- 
values window (as in the example below), you need to handle the communication 
yourself, using the information given below. An example of a situation in which this 
is necessary is when you have a frame, some panes of which are choose-variable- 
values windows. 
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Define Orchestra 



Contrabass: 2. 
Cello: 4. 
Viola: 4. 
Uiolin: 4. 
Flute: 4. 
Trunpet: 4. 
Harp: 1. 
Percussion: 2. 



Done Q 



Figure 22. Example of making a choose-variable-values menu. 
The Lisp code used to generate Fig. 22 is given next. 



;;; Choose Variable Values Example 4 

;;; In this example, the user specifies the number of 

;;; instrumentalists of each kind needed to define an orchestra. 



(defvar 
(defvar 
(defvar 
(defvar 
(defvar 
(defvar 
(defvar 
( defvar 



contrabass 2) 
cello 2) 
viola 4) 
violin 4) 
flute 4) 
trumpet 2) 
harp 1) 
percussion 2) 



;;;; Define the variable list 
(defvar instrument- list 

'((contrabass "Contrabass" : number) 

(cello "Cello" mumber) 

(viola "Viola" :number) 

(violin "Violin" :number) 

(flute "Flute" :number) 

(trumpet "Trumpet" : number) 

(harp "Harp" : number) 

(percussion "Percussion" mumber))) 

;;; Define the margin choice list 
(defvar margin-list '(("Done" nil 

tv:choose-variable-values-choice-box-handler nil nil))) 

;;; Hake the window 
(defvar choix 

( tv : make-wi ndow ' tv: choose- vari abl e-val ues-wi ndow) ) 
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;;; This function sets up the window, exposes it, 
;;; and calls appropriate routines 
(defun display ( ) 

(let ((base 10.) (ibase 10.)) ; Set the base to 10 
(send choix * :setup 

instrument-list 
"Define Orchestra" 
nil 

margin-list) 
The rsetup message is normally followed by the 
:adjust-geometry-for-new-variables message in order 
to coordinate the size of the window with the number 
of variables. The numerical argument (180.) tells 
it to adjust the width of the window to the precise 
size I want it to be. I could also have sent 
the : appropriate-width message, 
(send choix ':adjust-geometry-for-new-variables 180.) 
(send choix * :set-position 200. 200.) 
(tv:window-call (choix deactivate) 

blip holds the list returned by :any-tyi 
Look for a :choice-box blip 
(loop as blip = (send choix '-.any-tyi) 
until (eq (car blip) * :choice-box) 
do ( tv : choose-var i abl e-val ues-process-message 
choix blip))))) 



In order to invoke this menu, type the following form at the Lisp input editor: 

(display) 

The results are stored in contrabass, cello, viola, and the other instrument 
variables. 
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23. The Mouse-sensitive Items Facility 



The mouse-sensitive items facility is related to certain choice facilities such as the 
pop-up menus described previously. Like these facilities, the mouse is used to point at 
an object on the screen, and a box is drawn around an object when the mouse is 
over it. 

In contrast to a menu, in which mouse-sensitive behavior is limited to a relatively 
permanent item list, mouse-sensitive items are not a permanent part of a window. 
They disappear if the screen is cleared, for example. A main feature of a mouse- 
sensitive window is that graphical objects and text can be intermingled. The 
graphical objects themselves can be made mouse-sensitive. See the section "Mouse- 
sensitive Areas Example", page 286. 

For an example of mouse-sensitive items, try the [List Buffers] command in the 
Zmacs editor command menu (Figure 23). Move the mouse over the list of buffers 
and click the right-hand button. Another menu, keyed from a mouse-sensitive-item, 
is exposed. 



Buffers in Zmacs: 






Buffer name: 


Fi le Version : 


Major mode: 


h choi9.mss /dess/doc/roads/cho ice/ VIXtN: 


fc 


(Text)| 


choilB.mss /dess/doc/roads/cho ice/ VIXEN: 


\ 


(Text) 


choi?.mss /dess/doc/roads/cho ice/ VIXEN: 




(Text) 


choi8.mss /dess/doc/roads/cho ice/ VIXEN: 




(Text) 


choi5.mss /dess/doc/roads/cho ice/ VIXEN: 




(Text) 


choK.mss /dess/doc/roads/cho ice/ VIXEN: 




(Text) 


chroot.mss /dess/doc/roads/cho ice/ VIXEN: 




(Text) 


choi3.mss /dess/doc/roads/cho ice/ VIXEN: 




(LISP) 


HBuffer-ln 


[1 line] 


(Fundamental) 



Figure 23. Mouse-sensitive items. 

Mixing tv:basic-mouse-sensitive-items into a window flavor equips the window 
with mouse-handling according to the paradigm described in this section. Mouse- 
sensitive items are something you add in when defining your own window, rather 
than a complete facility. Consequently, there is no instantiate version. 

Note: The word "typeout" appears here and there in the mouse-sensitive items 
facility for historical reasons. Often mouse-sensitive items are typed out on top of 
some other display, such as an editor buffer. However, the mouse-sensitive-item 
facility has nothing to do with the typeout-window facility. See the section "Typeout 
Windows", page 174. 
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tv:basic-mouse-sensitive-items Flavor 

Mixing this flavor into a window provides for areas of the screen that are 
sensitive to the mouse. Moving the mouse into such an area highlights the 
area by drawing a box around it. At this point clicking the mouse performs 
a user-defined operation. This flavor is called basic because it usurps the 
handling of the mouse by the window; do not mix it with another flavor that 
also expects to use the mouse. However it is less basic than many basic 
flavors in that it does not do anything special with the displayed image of the 
window. 



23.1 Attributes of a Mouse-sensitive Item 

A mouse-sensitive item has three main attributes: 

• A type - a keyword that controls what you can do to it 

• An item - an arbitrary Lisp object associated with it 

• A rectangular area of the window - typically something is displayed in that 
area at the same time as a mouse-sensitive item is created, using normal 
stream output to the window. 

Unlike things such as menu items, mouse-sensitive items are not a permanent 
property of the window. They are just as ephemeral as the displayed text. This 
means they go away if you clear the window or if typeout wraps around and types 
over them. 

23.2 Associating Actions with Mouse-sensitive Items 

The :item-type-alist init-plist option specifies an alist that associates actions with 
types of items. Each element of the list contains the following elements: 

• A type keyword - for example, rvalue 

• A default operation ~ for example, a function name 

• A documentation string - displayed in the mouse documentation line when the 
mouse is pointing at an object of this type 

• A list of all the operations - (the default doesn't necessarily have to be a 
member of this list) This list is in the form of menu items, so typically each 
element is (name . operation) where the user sees the string name but the 
program identifies the operation by the symbol operation. In most cases 
operation is a function to be called, but it can be any atom. 
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Here is an example of an item-type-alist: 

((zweirfile 

zwei :find-defaulted-file 

"Left: Find file this file. Right: menu of Load, Find, Compare." 

("Load" : value zwei:load-defaulted-file 

documentation "Load this file.") 
("Find" :value zwei:find-defaulted-file 

documentation "Find file this file.") 
("Compare" : value zwei :srccom-file 

documentation "Compare file with newest version (srccom).")) 
(zwei: function-name 
zwei :edit-def inition 

"Left: Edit function. Right: menu (Arglist, Edit, Disassemble, Document.)." 
("Arglist" : value zwei :typeout-menu-arglist 

documentation "Print arglist for this function.") 
("Edit" :value zwei:edit-definition 

: documentation "Edit this function.") 
("Disassemble" :value zwei:do-disassemble 

documentation "Disassemble this function.") 
("Documentation" :va1ue zwei :typeout- long-documentation 

documentation "Print long documentation for this function."))) 

The tv:item-type-alist instance-variable can be initialized via the init-plist when the 
window is created. Normally, you do not create this alist directly. Instead, you use 
tv.add-typeout-item-type to build it up incrementally. See the section 
"tv:basic-mouse-sensitive-items Messages and Functions", page 2S3. 

23.2.1 Mouse Behavior 

The mouse works with a mouse-sensitive item in the following manner: 

• Mouse-left - Perform the default operation 

• Mouse-right - Pop up a menu of all the operations. Selecting one of these 
items performs it. 

• Mouse-right-twice - Call the System menu. 

• Other mouse clicks and clicking on an item whose type is not in the type alist 
— Cause a beep (the screen flashes) and generate an error. 

Performing an operation means that a command (also known as a blip)is sent to the 
controlling process through the :force-kbd-input message to the window. This 
command is a list (:typeout-execute operation item) y where operation is the 
operation and item is the arbitrary object remembered by the mouse-sensitive item. 
The ramifications of this, and how the operation is performed, are up to the 
application program. 
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tv:add-typeout-item-type Special Form 

The following special form is used to declare information about a mouse- 
sensitive type by adding an entry to an alist kept in a special variable. 

( tv: add- typeout-i tern- type 

alist type name operation default-p documentation) 

This alist can be put into the item-type alist of a mouse-sensitive window, 
using, for instance, the ritem-type-alist init-plist option. Note that each 
possible operation on a particular mouse-sensitive item type is defined with a 
separate tv:add-typeout-item-type form; this allows each operation to be 
defined at the place in the program where it is implemented, rather than 
collecting all the operations into a separate table. It also allows new 
operations to be added in a modular fashion. 

alist is the special variable that contains the alist. You should declare it nil 
with defvar before defining the first item type. Each program that uses 
mouse-sensitive items has its own alist of item types, so that there is no 
conflict in the names of the types. 

type is the keyword symbol for the type being defined. 

name is the string that names the operation. 

operation is the action to be taken, for instance, the function to be called. 

default-p is optional; if it is supplied and non-nil, it means that this operation 
is the default performed when you click the left button on an item of this 
type. 

documentation is optional but highly recommended; it is a string that 
documents what operation does. When the user points the mouse at an item 
of this type, the documentation line at the bottom of the screen displays the 
documentation for the default operation (reachable by the left button) and a 
list of the operations in the menu (reachable by the right button). If the 
user clicks right, calling for a menu, then the screen displays documentation 
for the operation pointed at. 

alist, type, and operation are not evaluated, name, default-p, and 
documentation are evaluated. 

When operation is a function, the tv:add-typeout-item-type form is 
typically placed near the definition of the function in the program source file. 
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23.3 tv:basic-mouse-sensitive-items Init-plist Options 

:item-type-alist alist (for tv:basic-mouse-sensitive-items) Init Option 

Remembers alist as the set of item types allowed in this window, alist 
should be created by tv:add-typeout-item-type. 



23.4 tv:basic-mouse-sensitive-items Messages and Functions 

The following messages are useful to send to a window with mouse-sensitive items. 
To create and display a list of mouse-sensitive items, use the function 
si:display-item-list. 

:item type item &rest format-args of Method 

tv:basic-mouse-sensitive-items 

This creates and displays a mouse-sensitive item of type type with associated 
object item. If format-args are supplied, they are a format control-string and 
arguments used to generate the display for this item. If format-args are not 
supplied, the display is generated with princ. 

:primitive-item type item left top right bottom of Method 

tv:basic-mouse-sensitive-items 

This is the primary means for creating a mouse-sensitive-area of the screen. 
It creates a mouse-sensitive item of type type with associated object item. 
When the mouse moves into the area, a box is overlaid around it. left, top, 
right, and bottom are the coordinates of a rectangular area of the window 
assumed to contain the display. The coordinates are "inside" coordinates. 
This is the same coordinate system that :read-cursorpos uses. 

si:display-item-list stream type list &optional item-string Function 

(order-columnwise t) 
Displays a list of items on stream in evenly spaced columns, stream must be 
interactive. If it supports mouse sensitivity, the items displayed are also 
made mouse sensitive. 

list is a list of items to be displayed. Each item in the list is displayed by 
sending the stream an :item message with type as the first argument. If 
the item is not itself a list, the item is the second argument to the :item 
message. 

If the item to be displayed is a list, the arguments to the :item message 
depend on item-string. If item-string is not nil, the second argument to the 
:item message is the first element of the item. If item-string is nil, the item 
should be an alist whose car is a string to be displayed and whose cdr is the 
item itself. In this case, the second argument to the :item message is the 
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cdr of the item, the third argument is ""A", and the fourth argument is the 
car of the item. The default for item-string is nil. 

If order-columnwise is not nil, the items are ordered down columns. If 
order-columnwise is nil, the items are ordered across rows. The default is t. 



23.5 tv:basic-mouse-sensitive-items Example 

An example of a mouse-sensitive items window is shown in Figure 24. It shows four 
mouse-sensitive items in a window. One of the items has been selected. Some 
graphic figures (not mouse-sensitive) have also been drawn in the window. For a 
description of the graphics operations: See the section "Graphic Output to 
Windows", page 118. 

The point of this figure is to show how in mouse-sensitive windows (unlike in 
regular menus) graphics and text can be intermingled. Notice the technique of 
combining the mixin flavors tv:borders-mixin and tv:top-box-label-mixin before 
tv:window to generate the boxed-in label at the top of the window. 



SHAPES 



Circle | Triangle I Rectangle Polygon 

▼ ■ # 



Figure 24. Mouse-sensitive items example. 

In Figure 25 one of the items [Triangle] has been selected, causing a menu of 
alternative actions to the the default action (default function) to appear next to it. 



SHAPES 


Circle Triangle ITunctionl 


e Polygon 


FunctiBn2 


A* wm \ Exit 



Figure 25. Result of selecting a mouse-sensitive item. 
The Lisp code used to produce Figure 25 is listed next. 
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;;; House-sensitive Example 

The functions called by the menus do nothing except increment 
some values. Check their values after instantiating the 
window to verify that the values were incremented. Also 
look at the value of the variable "blip". 



» > • 



Initialize variables 
(def const cl 0) 
(def const c2 0) 
(def const default 0) 
(defvar alist-alpha nil) 

;;; Define a new flavor of window, with a 

;;; centered top-label and a mouse-sensitive-item mixin 

(def flavor new () 

(tv:centered- label -mixin 

tv:borders-mixin tv: top-box- label -mixin 

tv: basic-mouse-sensitive- items 

tvrwindow)) 

;;; These define mouse-sensitive items 

(tv:add-typeout-i tern-type alist-alpha 

: new- type "Exit" (exit) 
nil "Exit and kill window") 

(tv:add-typeout-i tern- type alist-alpha 

: new- type "Function2" (function2) 
t "Add one to c2") 

(defun function2 () 
(setq c2 (+ 1 c2))) 

(tv:add-typeout-i tern- type alist-alpha 

:new-type "Functionl" (functionl) 
nil ?Add one to cl") 

(defun functionl () 
(setq d (+ 1 d))) 
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;;; Make the mouse-sensitive window 
(defvar sensitive-window 
(tv: make-window 

'new ; This is the flavor specification 

' : borders 2 

':top 200. 

': bottom 310. 

'rright 488. 

♦:width 316. 

* :blinker-p nil 

': label 'Ostring "SHAPES" :font fonts rbigfnt) 

':item-type-alist alist-alpha 

':font-map '(fonts:hl12))) 

;;; Expose the window and draw the objects 
(defun set-up ( ) 

(tv:window-call (sensitive-window :deactivate) 

(send sensitive-window ':item * mew-type " Circle ") 
(send sensitive-window ':item 'mew- type " Triangle ") 
(send sensitive-window ':item ' mew- type " Rectangle ") 
(send sensitive-window ':item 'mew-type " Polygon") 
(send sensitive-window ':draw-filled-in-circle 30. 50. 18.) 
(send sensitive-window ': draw- triangle 79. 36. 116. 36. 97. 68.) 
(send sensitive-window ': draw-rectangle 32. 32. 164. 36.) 
(send sensitive-window 

': draw-regular-polygon 265. 34. 288. 40. 5.) 
;; blip holds the list returned by :any-tyi 
(loop as blip = (send sensitive-window ':any-tyi) 

;; Invoke the operation returned by the blip 

;; unless the operation is (exit) 

until (equal (cadr blip) '(exit)) 

do (eval (cadr blip))))) 

; Do it 
(set-up) 



23.6 Mouse-sensitive Areas Example 

In Figure 26, we show how areas of the screen can be made mouse-sensitive, 
allowing the mouse to be used to select graphical entities, as well as text items. 

To make the shapes mouse-sensitive, within the function set-up, add several lines of 
Lisp code after the following line: 

(send sensitive-window ': draw-regular-polygon 250. 34. 272. 40. 5.) 
Next is the code to add to set-up. 
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Circle Triangle Rectangle Polygon 



Y k ■ 



Figure 26. Mouse-sensitive areas example. 



(defun set-up ( ) 



;; The boxes are associated with the graphic area 
(send sensitive-window 

*:primitive-item 'mew-type 'box-1 10. 30. 52. 74.) 
(send sensitive-window 

': primitive- item 'mew-type 'box-2 77. 31. 120. 72.) 
(send sensitive-window 

'zprimitive-item 'mew-type 'box-3 160. 31. 201. 72.) 
(send sensitive-window 

':primitive-item 'mew-type 'box-4 250. 31. 295. 75.) 
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24. The Margin Choice Facility 



A window can be augmented with choice boxes in its bottom margin using the flavor 
tv:margin-choice-mixin. See the section "The Multiple Choice Facility", page 251. 
Margin choice boxes give the user a few labelled mouse-sensitive points that are 
independent of anything else in the window. Thus margin-choices can be added to 
any flavor of window in a modular fashion. They are commonly used to implement 
"confirmation" choices (for example, [Do It] and [Abort]) following another selection. 

Margin choices are not a complete choice facility and consequently do not come 
supplied in an instantiate version. The margin choice facility must be combined 
with another window flavor. For an example of a window with margin choices (as 
well as choice boxes in its interior), try the [Kill or Save Buffers] operation in the 
Zmacs editor menu (refer to Figure 15 shown previously, page 251.) 



24.1 The tv:margin-choice-mixin Flavor 

tv:margin-choice-mixin Flavor 

This mixin flavor puts choice boxes in the bottom margin, according to a list 
of choice-box descriptors that can be specified with the :margin-choices init- 
plist option or the :set-margin-choices message. The choice boxes are 
spread evenly across the bottom margin. 

A choice-box descriptor is a list, defined as follows: 

(name state function xl x2) 

You can use a longer list as a choice-box descriptor and store your own data 
in the additional elements. 

name is a string that labels the box. state is t if the box has an "X" in it, or 
nil if it is empty. 

function is a function called by the system in a separate process if the user 
clicks on the choice box. It receives three arguments: the choice-box descriptor 
for the choice box, the "margin region" that contains the choice boxes, and 
the Y position of the mouse relative to this window. (The last two arguments 
are usually ignored.) When function is called, the special variable self is 
bound to the window and all its instance variables are bound to special 
variables. Place (declare (special self)) inside the function since self is not 
normally special. The structure access functions tv:choice-box-name and 
tv:choice-box-state may be of use inside function (they are just more 
specific names for car and cadr). If function changes the state of the choice 
box, it should refresh the choice boxes in the following way: 
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(send ( tv:margin-regi on- functi on region) ': refresh region) 

where region is its second argument. This is why the region argument is 
passed. Note that automatic implications of a choice (things that happen to 
the other choice boxes when one choice box is selected), such as in the 
multiple choice facility are not implemented in the margin-choice facility. See 
the section "The Multiple Choice Facility, page 251. Programmers must 
write their own implication routines. 

xl and x2 are used internally to remember the location of the choice boxes. 

tv:margin-choice-mixin is built on the non-instantiable flavor tv:margin- 
region-mixin; the position of the latter in the list of component flavors 
controls where in the margins the choice boxes appear. The default puts 
tv:margin-region-mixin right after tv:margin-choice-mixin To place the 
choice boxes inside the borders, use the following model: 

(defflavor bordered-window-with-margin-choices () 

tv:(borders-mixin margin-choice-mixin window)) 

24.2 tv:margin-choice-mixin Init-plist Option 

rmargin-choices choices (for tv:margin-choice-mixin) Init Option 

This causes a line of choice-boxes to appear in the bottom margin of the 
window, choices is a list of choice-box descriptors, described previously. If 
choices is nil, there are no choice boxes and no space for them in the bottom 
margin; however, the window is still capable of accepting the 
:set-margin-choices message to create a line of choice boxes later. 



24.3 tv:margin-choice-mixin Messages 

:set-margin-choices choices of tv:margin-choice-mixin Method 

This message changes the set of margin choices according to choices, which is 
nil to turn them off or a list of choice-box descriptors. If the choice boxes are 
turned on or off, the size of the window's bottom margin changes 
accordingly. 



24.4 tvimargin-choice-mixin Example 

A simple example of the margin choice facility is shown in Fig 27. In the example, 
the user can select one of three actions to be taken within a graphics window. 
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Rectangle D 



Circle Q 



Rbort D 



Figure 27. Example of a margin choice facility added to a window. 
The Lisp code used to produce Figure 27 is listed below. 



;;; Margin Choice Facility Example 

;;; Draws shapes or aborts based on the margin-choice selection. 

;;; Specify the margin choice-box descriptors 

(defvar choice-box-1 *(" Circle" nil shape-handler x y 

:draw-filled-in-circle 70. 75. 38.)) 

(defvar choice-box-2 '("Rectangle" nil shape-handler x y 

: draw-rectangle 70. 70. 170. 50.)) 

(defvar choice-box-3 * (" Abort" nil Abort-handler x y)) 

(defvar margin-list (list choice-box-1 choice-box-2 choice-box-3)) 

;;; Name of the window we create 

(defvar test-window) 

;;; Mixin the margin-choice facility with a window 
(defflavor window-with-margin-choices () 

(tv:borders-mixin tv:margin-choice-mixin tv:window)) 
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;;; Define a handler for the choice boxes that draw shapes 
(defun shape-handler (choice-box region y-pos) 

;; The special variable self will be the window 

(declare (special self)) 

y-pos ;not used, suppress compiler warning 

;; Hake just this box be lit 

(clear-other-choice-boxes choice-box) 

; ; Erase the window 

(send self ' :clear-screen) 

;; Refresh the margin so new choice box X*s are displayed 

(send (tv:margin-region-function region) ' rrefresh region) 

;; Draw the shape the user requested 

(apply self (nthcdr 5 choice-box))) 

;;; Define a handler for the "Abort" box 
(defun Abort-handler (choice-box region y-pos) 

;; The special variable self will be the window 

(declare (special self)) 

y-pos ;not used, suppress compiler warning 

;; Make just this box be lit 

( cl ear-other-choi ce-boxes choi ce-box ) 

;; Refresh the margin so new choice box X's are displayed 

(send (tv:margin-region-function region) * :refresh region) 

;; Remove the window from the screen 

(send self *: deactivate)) 

;;; This function clears the non-selected choice boxes 
;;; and sets the selected one 
(defun clear-other-choice-boxes (selected-box) 
(dolist (box margin-list) 
(setf (tv: choice-box-state box) (eq box selected-box)))) 

;;; Set up and expose the window 
(setq test-window (tv: make-window 

'window-with-margin-choices 

: borders 2 

: label nil 

:vsp 2 ; vertical spacing 

: font-map *( fonts rcptfont) 

:top 200. 

: bottom 500. 

:right 650. 

rwidth 410. 

:margin-choices margin-list 

:blinker-p nil 

:expose-p t)) 
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25. The Flavor Network of tv:menu 



tvtmenu is the basis of many of the choice facilities described in this text, tvrmenu 
is itself built on a network of flavors, shown in this diagram. tv:momentary-menu 
has a different network, which gives the flavor its own behavior. 
tv:command-menu is based on both tvrmenu and the tv:command-menu-mixin. 
Knowing the derivation of these flavors can be useful in investigating all the 
available options and in modifying them for special applications. 
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26. Init-plist Options for tv:menu 



This is a list of some useful window-oriented init-plist options accepted by the 
tvzmenu flavor and flavors built on it. It is not meant to be a comprehensive list. 
Use the Flavor Examiner to find out all the init-plist options of a particular flavor. 
Most of these options are also documented elsewhere: See the section "Using the 
Window System", page 71. 

:activate-p t-or-nil (for tv:menu) Init Option 

If this option is specified non-nil, the window is activated after it is created. 
The default is to leave it deactivated. 

:borders argument (for tv:menu) Init Option 

This option initializes the parameters of the borders. The argument can be 
nil, which specifies no borders, t, which specifies default borders, or it can be 
a specification of a border. The specification indicates which function is used 
to draw the border and how thick the border is, in pixels. 

If the specification is a number, the border is drawn by the default function 
at the specified thickness. The default function is 
tv:draw-rectangular-border. 

If the specification is a symbol, the border is drawn by the specified function 
at a default thickness. For more details on creating a function: See the 
section "Using the Window System", page 71. 

If the specification is a cons in the form (function . thickness), the borders 
are drawn by the specified function at a specified thickness. 

The specification can also be a list of locations on the screen: (left top right 
bottom). 

rbottom bottom-edge (for tvtmenu) Init Option 

This is specified in pixels and is relative to the outside of the superior 
window. 

:character-height spec (for tvrmenu) Init Option 

This is a way of specifying the height of the window. The inside height of 
the window is made large enough to display spec number of lines in font zero 
(the first font in the font map). If the spec is a string containing carriage 
returns, then it is made tall enough to accommodate the string. 

:character-width spec (for tv:menu) Init Option 

The spec is either an integer or a character string. This is one way to 
specify the width of the window. The inside width of the window is made 
large enough to display spec number of characters in font zero (the first font 
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in the font map). If the spec is a string, then it is made wide enough to 
display the string. 

:columns n-columns (for tv:menu) Init Option 

Sets the number of columns in a menu. 

:default-font font (for tv:menu) Init Option 

Sets the default font. Items whose font is otherwise unspecified are displayed 
in the default font. 

redges (left-edge top-edge right-edge bottom-edge) (for tvrmenu) Init Option 
Sets various position and size parameters. All the edge parameters are set 
relative to the outside of the superior window. 

:edges-from source (for tvrmenu) Init Option 

Specifies that the window gets its edge information from the source. If the 
source is a stringy the inside of the window is made large enough to display 
the string in font 0. If the source is a list: {left-edge top-edge right-edge 
bottom-edge) it is the same as the redges option. If the source is mouse, 
the user is asked to point to where the left-top and right-bottom corners 
should go. If the source is a window, the window's edges are copied. 

:expose-p t-or-nil (for tvrmenu) Init Option 

When this option is set to t the window is immediately exposed. Otherwise, it 
must be explicitly exposed with an :expose message. 

:fill-p t-or-nil (for tv:menu) Init Option 

Specifies whether to use filled format or columnar format. 

:font-map list (for tvrmenu) Init Option 

Specifies a list of fonts associated with the window. 

rgeometry list (for tv:menu) Init Option 

Sets up the complete menu geometry, using a list to specify the columns, 
rows, inside-width, inside-height, max-width, and max-height. See the section 
"The Geometry of a Menu", page 213. 

rheight arg (for tv:menu) Init Option 

Height in pixels. Includes margins, as opposed to rinside-height, which does 
not include margins. 

rinside-height arg (for tvrmenu) Init Option 

Tnsirlp Vipicrht RTw»ifieH in nivola "Rvy»1ii r?oa irmrorina 



s-neigni arg uor tvrmenu; 

Inside height specified in pixels. Excludes margins 



:inside-size (inside-width inside-height) (for tvrmenu) Init Option 

Inside size parameters specified in pixels. 
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:inside-width arg (for tvrmenu) Init Option 

Inside width of window specified in pixels. 

:item-list list (for tvrmenu) Init Option 

Specifies the item list associated with a menu. 

:label specification (for tv:menu) Init Option 

Specifies the menu's label. The specification is usually a list in the following 
form: 

(:string "Foo" :font font-specification) 

:left arg (for tvrmenu) Init Option 

Specifies the left edge of the menu, defined in pixels relative to the outside of 
the superior window. 

:mininram-height arg (for tvrmenu) Init Option 

:minimum-width arg (for tvrmenu) Init Option 

In combination with the :edges-from rmouse init option, 
:minimum-height and :minimum-width specify the minimum size (in 
pixels) of the rectangle accepted from the user. If the user tries to specify a 
size smaller than one or both of these minimums, the screen beeps and the 
system prompts the user with a new left-corner. 

:name string (for tvrmenu) Init Option 

This names the window. The name appears in such places as the list of 
windows generated by [Select] in the System Menu and in the window 
display option of Peek. The name is the default string for the label if another 
label string is not specified. 

rposition (left-edge top-edge) (for tv:menu) Init Option 

Specifies the left and top edges of the window. All specifications are given 
with respect to the outside of the superior window. 

:reverse-video-p t-or-nil (for tvrmenu) Init Option 

If this option is set to t the menu is displayed in reverse video, that is, 
white-on-black instead of black-on-white. 

rright right-edge (for tvrmenu) Init Option 

Right edge of the window specified in pixels, relative to the outside of the 
superior window. 

:rows n-rows (for tv:menu) Init Option 

Sets the number of rows. 
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:screen screen (for tv:menu) Init Option 

In a system with multiple screens, sets the screen on which the menu 
appears. 

:top top-edge (for tv:menu) Init Option 

Top edge of the window specified in pixels, relative to the outside of the 
superior window. 

:vsp n-pixels (for tvrmenu) Init Option 

Sets the vertical spacing between lines in the menu. The default is 2 pixels. 

rwidth arg (for tvrmenu) Init Option 

Specifies the width of the window in pixels. 

:x arg (for tv:menu) Init Option 

Specifies the left edge of the menu in pixels, relative to the outside of the 
superior window. 

:y arg (for tv:menu) Init Option 

Specifies the top edge of the menu in pixels, relative to the outside of the 
superior window. 
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27. Messages Accepted by tv:menu 



These are some of the messages (arranged in alphabetical order) accepted by menu 
flavors built on tv:menu. The list is not meant to be comprehensive. Use the 
Flavor Examiner to find out all the messages accepted by a particular flavor. Most 
of these messages are also documented elsewhere: See the section "Using the 
Window System", page 71. 

deactivate of tvrmenu Method 

This message deactivates a window, deexposing it. In momentary menus, it is 
sent when the mouse is moved outside the borders of the menu. 

rdeexpose of tv:menu Method 

Causes a menu to be deexposed. The window remains activated. This 
message is normally sent only by the system. It usually is meaningless if sent 
by a user program, because the window is exposed again immediately. 

:expose of tvrmenu Method 

Causes a menu to be exposed, that is, displayed on the screen. 

rrefresh &optional type of tvrmenu Method 

Redraws the menu. The system sends this message with different type 
symbols depending on the event that caused redrawing. You can also send it; 
in this case the type argument is usually not supplied and is allowed to take 
on a default value. The menu refreshes itself from a bit-save array or 
redraws itself from scratch, as appropriate. If the bit-save array is invalid, or 
type is rcomplete-redisplay (this is the default), or the size of the menu 
has changed, it redraws from scratch. 

:set-default-font font of tvrmenu Method 

Sets the default font of a menu. It accepts a font specification, such as 
fonts:trl2, as its argument. All text in a menu whose font is not otherwise 
specified is set in the default font. 

:set-edges new-left new-top new-right new-bottom of tvrmenu Method 

This message sets the edges of the window to the four values supplied as 
arguments, in pixels relative to the superior window. 

rset-item-list list of tvrmenu Method 

Sets the item list of a menu. 

rset-label label of tvrmenu Method 

Sets the label of a menu. 
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28. Introduction to Scroll Windows 



Scroll windows are a flavor of window provided by the Lisp Machine window system 
to facilitate building programs that display information that updates itself, changes 
its format, responds to the mouse, and shows other evidences of "live" behavior. To 
see many examples of this type of window, press select p to invoke the Peek 
subsystem, and observe the behavior of its various displays as the objects they 
represent change state. 

The basic service performed by scroll windows is that of redisplay. You provide a 
scroll window with a data structure defining what is to be displayed and how to 
display it. This is very different from other windows that you simply instruct to 
display text (and sometimes graphics) by telling them what to display. While a 
normal window simply draws what it has been asked to display, a scroll window 
remembers how to display again what it is now displaying, when instructed to do so. 
Also, a scroll window knows how to update its display, changing only those portions 
of the display that need changing. This is very much like what a real-time editor 
does when you change text. 

A typical use of scroll windows is to display a structured representation of some data 
structure in your program. By clicking on mouse-sensitive items, you can ask to 
"display more detail" about some item on display. Your program and the scroll 
window would negotiate to display the more detailed items under the selected item, 
and move other items around. The file system editor and the Window hierarchy 
display in Peek do this. Another typical use is to display data about activity in the 
Lisp Machine going on simultaneously in other processes, while you watch the 
display. Such a display might have lines consisting of fixed text followed by numbers 
or strings that are the "values" of the quantities being "watched". For instance, 
some lines of such a display might read as follows: 

Total polyhedra measured 603 
Global eccentricity (av.) .82% 

while you watched; the numbers change (update) as the program measures new 
polyhedra. 

Note tnat "scroll windows" have nothing, in particular, to do with the concepts of 
scrolling of windows in general and of mouse scrolling commands in particular. The 
name "scroll window" is something of a misnomer and a historical accident. Scrolling 
is not really what is important about scroll windows: the important thing that they 
provide is a convenient mechanism for getting information to redisplay. 

Scroll window displays are exciting and enjoyable to watch and use, and add a touch 
of class to any program that uses them. 
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29. Basics of Scroll Windows 



The flavor of scroll window most often used is tv:scroll-window. You can call 
tv:make-window to make a scroll window. There is also tv:basic-scroll-window 
that contains nothing more than the feature of being a scroll window, and can be 
used to build more highly specialized flavors. You might also be interested in 
tv:scroll-window-with-typeout. It provides an inferior typeout window should 
random program output occur directed at it. 

The various fields to be displayed are described by items. Each item corresponds to 
some logical portion of the display, always an integral number of lines. Items often 
contain other items (in a hierarchical fashion), and items can be added and removed 
from items dynamically (which, as is the whole point of scroll windows, causes the 
objects on display to appear and reappear when the scroll window's display is 
redisplayed). 

A scroll window displays exactly one top-level item. The top-level item is simply an 
item corresponding to all the data to be displayed in in the scroll window. When 
you have constructed the top-level item, you hand it to the scroll window via the 
:set-display-item message. You normally create and set the top-level item just 
once, when you create and initialize the scroll window. 

:set-display-item item of tv:basic-scroll-window Method 

Set the top-level item of the scroll window to item. 

The display created by the items given to a scroll window may well be larger than 
the physical dimensions of the window. Scroll windows handle this elegantly by 
showing only a portion of the total display, and allowing the user to scroll the data 
of the display in the window by using the mouse scrolling commands. 

You cause a redisplay by sending the window a redisplay message. 

redisplay of tv.-basic-scroll-window Method 

When a scroll window is sent the :redisplay message, it examines all parts 
of the top-level item, including all items contained in it and all items 
contained in them and so on. It adds new lines to the display as they are 
found, removes ones no longer found, and updates ones still found, that are 
in need of updating. 

There are two types of items: line items and list items. A line item describes 
information to be displayed on exactly one line of the display; that is, if the portion 
of the display controlled by a certain line item is visible in the window, then it uses 
up exactly one line of the window, and all of the information of the line item must 
fit in that line. Drawing a line item must not ever try to move to the next line 
(you shouldn't use return characters). 
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A line item is built up of a sequence of entries. Each entry is responsible for 
controlling how one field of the line is drawn. The entries in a line item can be any 
mixture of constant strings or dynamically updated quantities. The descriptions of 
the dynamic quantities provide instructions for obtaining and displaying their values. 
The formats of these descriptions are given below. When the window is asked to 
redisplay, all of the dynamic entries of the line items on display are computed 
according to these instructions, and the fields of the line to which they correspond 
are dynamically and incrementally updated if they need to be. 

List items describe multiple-line objects to be displayed. A list item is little more 
than a list of other items, themselves line items or list items. A list item is 
displayed by displaying all of the elements in it, in the order in which they appear in 
the list. The way you insert and remove lines of the display is by adding elements 
to and deleting elements from list items. 

A list item is simply a Lisp list. Its first element is a list item plist, specifying some 
advanced options to be discussed below, and its remaining elements are the items 
logically comprising the list item. In most cases, the list item plist may be left 
empty (that is, nil). 
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30. Constructing Items 



Line items are constructed 'by a specialized function, described below. List items are 
constructed by the standard Lisp list-building functions. 



30.1 Constructing Line Items 

Line items are constructed with the following function: 

tv:scroll-parse-item &rest line-item-spec Function 

This function receives its arguments as a single &rest argument that is a 
line item spec. It constructs and returns a line item. For the format of line 
item specs: See the section "Constructing Line Items", page 307. 

The line item spec consists of two portions: global line attributes that are optional, 
and entries, specifying the fields to be displayed, in the order they are to be displayed 
on the line. The global line attributes are keyword/value pairs of elements. The 
first even-numbered element of the line item spec that is not a symbol is the first 
entry (all keywords are symbols), nils are ignored in any position of the line item 
spec; this sometimes makes the specs easier to construct. Every occurrence of nil is 
deleted from the spec before further processing. 

Here is a simple call to tv:scroll-parse-item. 

( tv: scrol 1 -parse- i tern 

': mouse '(DOUGHNUTS) 

"Number of doughnuts: " 

' (:symeval food:doughnut-holes nil ("~D"))) 

Here the global line attributes are present, and consist of the following: 

• .-mouse '(DOUGHNUTS) 
There are two entries: 

"Number of doughnuts: " 

(:symeval food:doughnut-holes nil ("~D")) 

In the above example, the :mouse global line attribute makes the line displayed by 
this line item be mouse-sensitive, and the data item (DOUGHNUTS) will be encoded 
in the blip fed to the window's input buffer when this line is clicked upon. The 
meanings of the various global line attributes will be discussed in detail later. 

There will be two fields displayed on this line: the fixed string 
"Number of Doughnuts: ", and the value of the global variable 
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food:dougbnut-holes. The latter value will be displayed as a decimal number (the 
""D" is a format control string), immediately after the "Number of doughnuts: " 
string, on the same line. 

Whenever the window displaying this item is asked to redisplay, the displayed value 
of food:doughnut-holes will be updated if the value of that variable has changed. 

30.1.1 Line Item Entries 

An entry in a line item spec can either specify a constant string to be displayed, or it 
can specify how to find a value to be displayed. There are four types of entries: 
string, symeval, function, and value. An entry is ordinarily represented as a list, 
whose first element is one of the keywords rstring, :symeval, rfunction, or 
rvalue. 

There are two exceptions. First, when an entry is to be made mouse-sensitive, two 
extra elements are included at the front of the list. See the section "Mouse 
Sensitivity", page 311. Secondly, there are shorthand forms for some of the formats; 
they are listed in the table below. 

Here are the four types of entries, and their respective formats: 



rstring 



Format: (:string string) 

Shorthand format: string 

where string is a string. This entry will display as the string, occupying as 
much of the line as it takes up. 



rsymeval 



Format: (rsymeval symbol width (format-ctl base *nopoint)) 

Shorthand format: symbol 

where symbol is a symbol to be evaluated to produce the value to be 
displayed. The syntax symbol is equivalent to 

(rsymeval symbol nil ("-A" base *nopoint)) 

The third and fourth elements of the entry are optional, width specifies the 
field width in characters, on the line, to be allocated to the displayed data. If 
omitted, or given as nil, as much space as needed will be allocated. If a 
value is given, it must be a positive number that must fit in the window's 
line length. The printed representation of the value should not use more 
than this many characters. 

The value is printed using the format function. The fourth element of the 
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entry is a list, whose first element specifies the format control string to be 
used. If there is no fourth element, ""A" is used. The second and third 
elements of this last element of the entry (which are also optional) give the 
values of the global variables base and "nopoint to be set up when format 
is called. If not given, the current values of these variables at redisplay time 
will be used. 

Note that if you use the shorthand form of the rsymeval entry type as the 
first entry in the line item spec, it will be mistaken for a keyword in the 
global line attributes. If you want the first entry to be a rsymeval entry, 
you must use the longer syntax. 

Here are some examples of rsymeval entries: 

( rsymeval number-of-dogs) ; Just display the value, 

number-of-dogs ; (The same.) 

(rsymeval number-of-dogs 6 ("~S")) ; Use six columns and 

; use slashification. 



rfunction 



Format: (:function function arglist width (format-ctl base *nopoint)) 

Shorthand format: (lambda ) 

Shorthand format: (named-lambda ....) 

Shorthand format: <an actual compiled code object > 

This is the most general type of entry. It specifies a function to be called at 
redisplay time, and the actual arguments to which it is to be applied. If 
obtaining the data to be displayed for an entry involves any action more 
complicated than the evaluation of a variable, you will need a :function 
entry, function specifies the function to be called. It may be a symbol, 
lambda expression, or named-lambda expression, or compiled code object. It 
will be applied to arglist at redisplay time to produce the value to be 
displayed. Keep in mind that arglist is a list of actual values, not a list of 
forms to be evaluated. If arglist is not given, it is assumed to be nil. It is 
often useful to use the backquote list-templating facility to create -.function 
entries whose argument lists contain actual data objects obtained at the time 
tv:scroll-parse-item is called. See the section "Backquote" in Reference 
Guide to Symbolics-Lisp, 

width, format-ctl, base, and *nopoint are optional, and have the same 
meaning as they do with rsymeval entries. 

In the shorthand forms, in which only a function is supplied, arglist is 
assumed nil and default assumptions about the printing format are made as 
for rsymeval entries. 

Here are some examples of rfunction entries: 
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(rfunction #'compute-number-of-i terns '(dogs)) 
(:function #'compute-number-of-items '(dogs) 6 C-'S")) 
(lambda () (compute-number-of-cats)) 



rvalue 



Format: (rvalue index width (format-ctl base *nopoint)) 

rvalue entries are a trick to obtain multiple results or decompose structured 
results from functions. Since rfunction entries can return only one value to 
be displayed, it is more difficult to display a complicated result, or multiple 
values returned by a function, than to display a single result. Scroll windows 
provide a one-hundred element array in which functions called by rfunction 
entries may store extra results, rvalue accesses elements of this array for 
display: index is a number that specifies what element of the array to access. 
By using this array as a temporary holding place, values computed by a 
rfunction entry early in the line item can be accessed by rvalue and 
rfunction entries later in the line item. 

The array can also be accessed via the accessor tvrvalue from functions in 
rfunction entries. This accessor is applied to the array element index into 
the array tvrvalue in question, setf may be used to store values into this 
array. 

width, format-ctl, base, and *nopoint are optional, and have the same 
meaning as they do with rsymeval entries. 

Here is an example of the use of a rvalue entry. We wish to display a line 
item that contains two constant strings and two variable fields. The line will 
represent the result of calling a function, current-horse-lister, that returns 
lists such as: 

(Seabiscuit Silver Horace) 

This function interrogates the state of some horse-processing system that is 
assumed to be running and continually processing horses. We wish to display 
on one line the number of horses currently being processed, and the actual 
list of their names. 

A first attempt might look like 

(tv: scroll -parse- item 

"Number of horses :" 
'(rfunction (lambda () 

(length (current-horse-lister))) 
5 

("~5D")) 
"Their names: " 
'( rfunction #'current-horse-lister)) 
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Although this will produce a display of the right format, it is inadequate 
because it calls current-horse-lister twice. It is possible that between the 
two calls to current-horse-lister the set of horses may have changed. Or 
we could be dealing with a function that has side effects, and must not be 
called twice if we really only want one answer, -.value solves this problem. 
Here is the correct code. 

( tv : scrol 1 -parse- i tem 

"Number of horses : M 
* ( : function 

(lambda ( ) 
(setf (tv:value 0) 

( current-horse- 1 ister) ) 
(length (tv:value 0))) 
5 ("~5D")) 
"Their names: " 
*(:value 0)) 

In this example, element of the array is used to save the horse list 
between the display of the second and fourth entries in this item. 

You should not use tvtvalue except for this purpose, and you should only 
expect its values to be saved during the display of one line item. It cannot 
be counted on to retain values between displays of different items, or 
repetitive displays of one item. 

30.1.2 Mouse Sensitivity 

Entire line items or individual entries in a line item may be made mouse-sensitive. 
This means that the display corresponding to the item or entry will be highlighted 
as the user moves the mouse over it, and if the user clicks on it, the program 
controlling the scroll window will be notified. 

If you want to use any of the mouse sensitivity features, you must include the flavor 
tv:scroll-mouse-mixin in the flavor of window to be used. This mixin is not 
included in tv:scroll-window. (Note: this has nothing to do with mouse scrolling; 
the name means that it is the flavor of the scroll facility that deals with the mouse.) 

To make a line item mouse-sensitive, put a specification of the form 

: mouse action 

or 

:mouse-self action 

in the global line attributes of the line item spec when constructing the line item. 
action must be a list (actually, a cons). When a mouse-sensitive item is clicked on, 
the scroll window's handler, running in the mouse process, does one of the things 
described below, depending on the car of action. 

If the car of action is nil, action is interpreted as a menu item. Clicking causes an 
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texecute message is sent to the window, with action as its argument. Only those 
menu item types that produce side effects are meaningful here (that is, rfuncall, 
:eval, :kbd, :menu, and :buttons). You can also use rdocumentation to provide a 
string to be displayed in the mouse documentation window in the who-line. Note 
that the car of action is not significant to :execute. For example: 

(tv: scroll -parse- item 
*:mouse '(nil :eval (set-balance 0) 

: documentation "Set the balance to zero.") 
"Current balance: " balance) 

When you move the mouse over this line of the display, the entire line is 
highlighted, and the documentation string appears in the who line. If you click on 
the line, the function set-balance is applied to 0. 

If the car of action is a symbol other than nil, that symbol is looked up in the type 
alist, which is an association list. If the car is found, an .-execute message is sent 
to the window. The argument to the message is the list 

(nil op . action) 

where op is the cadr of the entry found in the type alist for the car of action. The 
type alist can be set with the :set-type-alist message, or initialized with the 
:type-alist init option. 

If the car of action is not found in the type alist (which will happen if you aren't 
using the alist feature) and is not nil, a blip of the form 

(type action window button) 

is forced into the window's input buffer. Here, type is the car of action, window is 
the window itself, and button is a mouse button encoding. See the section "The 
Character Set" in Reference Guide to Streams, Files, and I/O. This is the standard 
way to "read" the event of clicking on a sensitive item. The doughnut example 
above used this technique, putting blips of type DOUGHNUT in its input stream. 

:mouse-self is just like rmouse, except that before returning the line item, 
tv:scroll-parse-item walks over action, and substitutes the actual line item that it 
constructed for all occurrences of the symbol self in action, so you can access its 
array leader. See the section "Line Item Array Leaders", page 313. 

Individual entries in a line item can be made mouse-sensitive, as well. To make an 
entry mouse-sensitive, express it in the standard form, that is, (as opposed to the 
shorthand form), as follows: 

(:string "Differential Amplifiers") 

Then place either of the following at the head of the list: 

rmouse action 
or 

:mouse-item action 
The new entry will precede what was there before. For example: 
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(: mouse (nil :menu parts -menu 

: documentation "Pop up a menu of parts.") 
rstring "Differential Amplifiers") 

rmouse acts just like it does for entire line items, and action has precisely the same 
interpretation. Instead of :mouse-self, use :mouse-item to get the substitution 
feature: for mouse-sensitive entries, the item (that is, the item for the whole line) is 
substituted for all occurrences of the symbol item in action if :mouse-item is 
employed. 

30.1.3 Line Item Array Leaders 

You can use the array leader of a line item for arbitrary data storage. You can use 
:mouse-self or :mouse-item to get the items back at mousing time. Scroll windows 
use the first few entries in the array leader of a line item for its own purposes. 
The index of the first item available for your use is stored in the variable 
tv:scroll-item-leader-offset. 

To specify that you want array leader space to be reserved at line item creation 
time, you must use the deader global line attribute. Its formats are 

: 1 eader size 

: 1 eader init-list 

size is the amount of array leader to be reserved for your purposes, and init-list is a 
list of elements to be placed at line item creation time in as many array leader 
elements as they require. 



30.2 Constructing List Items 

List items are normally constructed with the function list. The first element of a 
list item is the list item plist, and the rest of the elements are items that make up 
the list item. 

Here is an example of constructing a list item for a three-line display: 

(list () ;list item plist 

(tv:scroll -parse- item ...) 
(tv:scroll-parse-item ...) 
(tv: scroll -parse- item ...)) 

The list item plist is a list of alternating keyword symbols and values. There are 
two defined keywords, as follows: 

:pre-process-function 

The :pre-process-function keyword takes any function object as an 
argument. This function is called at redisplay time, with the entire list item 
as as its one argument. Its returned value is ignored. The idea of this is to 
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allow you to compute, at redisplay time, whether or not you still want all the 
items currently in the list item to remain in it, or want to add new ones and 
so on. Your "pre-process function" will have to walk over the cdr of the list 
item, and be aware that lists therein are list items and arrays are line items 
in whose array leader you may have stored identifying information 
meaningful to you. 

rfunction 

(Not to be confused with the :function entry type in line items.) The 
rfunction keyword takes any function object as an argument. When it is 
time to redisplay this list item, the function is called to process every item of 
this list item, and the returned value of the function is rplaca'ed back into 
the list item before the redisplay is done. This processing occurs after the 
pre-process function, if any, has been called. 

The idea of the tfunction list item property is to allow scroll window 
redisplay to actually cause your subsystem to update its own data. Some 
subsystems might want or require this, although it is very uncommon. 

The function is called on three arguments: inferior-item, position, and plist. 
inferior-item is the particular constituent item of the list item, position is an 
internal item index, and plist is a locative to the list item plist of the current 
list item. The result of function is rplaca'ed back into the list item when 
function returns. 
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31. Virtual List Maintenance 



An elegant facility to construct and maintain list items is provided by 
tv:scroll-maintain-list. If you intend to construct displays in which lines and 
subdisplays dynamically appear and disappear, you probably want to use this facility 
to construct and update list items. It uses the list item plist facilities described above 
for its implementation. 

The function tv:scroll-maintain-list constructs (and returns to you) a list item that 
updates itself to represent some object of yours and its inferior objects every time 
the scroll window is asked to redisplay. You provide tv:scroll-maintain-list with 
two functions, one (the init function) that will be called at redisplay time to produce 
some object of yours corresponding to a set of your objects that require associated 
displays, and a second (the item function) that, given an object of yours, produces 
the display item (line or list) representing it. 

As just described, the set of objects is expected to be a list of your objects. 
tv:scroll-maintain-list will ask for it at each redisplay, and cdr down it, applying 
your item function to get display items. It is also possible to return a set of your 
objects in some other form than a list; in this case, you must provide a stepper 
function that knows how to extract the next object, the "rest" of the set, and tell 
whether the end has been reached. 

tv:scroll-maintain-list init-fun item-fun &optional per-element-fun Function 

stepper-fun compact-p pre-proc-fun &rest 

init-args 
Constructs and returns a list item that updates itself when the scroll window 
is asked to redisplay. Takes the following arguments: 

init-fun The init function that will be called at redisplay time to 

provide a representation of the set of objects to be 
displayed. 

init-args Arguments to be passed to init-fun when called at 

redisplay time. 

item-fun The item function, to be applied to each object of yours to 

produce a display item. 

per-element-fun A function to be put in the list item plist of the list item 
as the :function function. 

stepper-fun The function that is called on the set of objects and all 

"rest"s of the set. It is expected to return three values: 
the next element, the "rest" of the set, and t if it has 
returned the last element of the set. If not given, 
stepper-fun defaults to tv:scroU-maintain-list-stepper, a 
function that handles ordinary lists. 
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compact-p An optional flag that causes tv:scroll-maintain-list to 

copy the list it builds at each redisplay into a special area 
for such lists, in order to optimize paging performance. 
The list so constructed will be stored in compact (that is, 
cdr-coded) form. 

pre-proc-fun A function to be put in the list item plist of the list item 

as the :pre-process-function function. If not given, 
pre-proc-fun defaults to 
tv:scroll-maintain-list-update-functiorL 

Following is a simple example: 

(tv:scroll-maintain-list #'( lambda (instance) ;The init function 

(send instance *:value-list)) 
#'( lambda (value) ;The item function 

(tv: scroll -parse- item 

*(:string .(format nil "~S" value)))) 
nil nil nil nil 
self) ;Argument to init function 

Here is an example of code to construct a list item that displays the contents of a 
Lisp list on separate lines. The variable *important-data* contains the list. 

(tv: scroll -maintain- list 

#*( lambda () *important-data*) ; The init-fun. 

#'( lambda (list-element) ; The item- fun. 

;; Create an item from the list element. 
( tv.-scrol 1 -parse- i tern 

*(:string .(format nil "~S" list-element))))) 
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32. Introduction to the Digital Audio Facilities 



The 3600 audio facilities consist of two 16-bit digital audio channels and supporting 
microcode. The facilities read arrays of samples from 3600 memory and feed them 
to the console at a rate of 50,000 pairs of samples per second. This rate is controlled 
in hardware by a crystal. When active, the audio microcode reads a pair of samples 
from 3600 main memory every 20 microseconds, supplying one 16-bit value to each 
channel. 

In the standard console, the samples are sent to a 12-bit digital-to-analog converter 
(DAC). The signal emanating from the DAC is routed to a small speaker and an 8- 
ohm headphone jack, as well as a low-level analog output compatible with standard 
"auxiliary" inputs to consumer audio equipment. In the standard console, the 
monoraul output sound is produced by combining the two DAC channels and routing 
the signal through a simple two-pole low-pass filter at 8 KHz. 

The 3600 audio microcode also supports a polyphony feature. The polyphony feature 
allows the use of the audio facility for the performance of music, obviating the need 
to generate samples for an entire performance. The polyphony feature is 
experimental in release 6.0; it may be radically altered or removed in future releases. 

Use the online tools described elsewhere to find out more about a given object in the 
audio facility: See the section "Program Development Tools and Techniques" in 
Program Development Utilities. For practical examples of programming with flavors: 
See the section "Window System Program Examples". 

The digital audio facilities are demonstrated through several code examples. See the 
section "Examples of Using the Audio Facilities", page 339. The code examples are 
distributed in the following file: 

SYS : EXAMPLES ; AUDIO-EXAMPLES . LISP . 

Note: the digital audio facility works only on 3600-family Lisp Machines running 
System 5.2 (or later), with the Revision 6 (or later) I/O board (IO-REV.6) installed. 
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33. Microcode Support for the Digital Audio Facilities 



33.1 The Audio Microtask 

This section discusses the microcode interface, that is, the formats of commands and 
samples interpreted by the audio microcode. This is the lowest-level interface to this 
facility, and only the barest primitives are described here. The formats and 
commands given here might change in future versions of the hardware, microcode, 
and software. 

The audio microcode runs in its own microtask and thus operates parallel with the 
execution of Lisp. The audio microtask is either active or stopped at any time. 
Since the microtask scheduler works according to a priority queue, when the audio 
task is active, it "wakes up" every 20 microseconds, and executes, preempting Lisp, 
until it either outputs an audio sample pair or stops. The generation of audio 
samples is not affected by the behavior of Lisp programs, including the masking of 
interrupts, and so forth. 

When active, the audio microtask follows a command list, or program of its own, 
consisting of audio commands, stored by the programmer in main memory before 
the audio microcode is started. The command list is stored in sequential physical 
memory locations (although it can contain "jumps"). Each command occupies one or 
more 3600 words. The words are expected to be fixnums. The 32 data bits of each 
fixnum contain the data interpreted by the audio microtask. The commands include 
directives to control the flow of the command list as well as directives to output data 
to the console DAC. The audio microcode also maintains a repeat counter to facilitate 
generation of repetitive or continuous waveforms. See the section "Looping Through 
Audio Command Lists", page 334. 

The audio microtask is started by the execution of the %audio-start instruction by 
Lisp; the evaluation of the form (sys:%audio-start) effects this. When this 
instruction is executed, the audio microtask fetches the physical address of the 
beginning of the command list from the variable sys:%audio-command-pointer. 
Therefore, this variable must be set to the physical address of the beginning of the 
command list prior to the execution of the form (sys:%audio-start). The audio 
microcode stops when it encounters an explicit command to this effect in its 
command list. 

The audio microtask is coded for real-time performance; it does no validity checking, 
and issues no diagnostics. If you program the audio microtask via the techniques 
described in this document, it is your responsibility, as always, to create valid 
programs. In the case of the digital audio facilities, however, the result of an invalid 
program could be a machine halt or destruction of the integrity of virtual memory, 
or both. If certain bit patterns are interpreted as audio commands, they can modify 
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storage locations. Save your editor buffers often when debugging code for the audio 
microcode. 



33.2 Sample Format 

Each sample pair is expected to be a fixnum. The 32 data bits of each fixnum 
include two samples, one for each channel. The sample pair is read by the audio 
microtask in one operation, and the samples are sent to each channel in parallel. 
Each sample is a 16-bit unsigned integer, one in the lower (bits 0-15) half word 
(channel 0), and one in the upper (bits 16-31) half word (channel 1). 

A sample value of produces the lowest analog output voltage, and a sample value of 
all Is (65535, octal 177777) produces the highest. A voltage of zero is represented by 
the midpoint value, 32768 (octal 100000). 

Channel is currently supplied with analog output hardware in the console; Channel 
1 is not. The digital-to-analog converter in the console is only of 12-bit precision, and 
thus, it ignores the low 4 bits of Channel samples. 



33.3 Audio Command Format 

Audio commands occupy one or more words of sequential physical memory. The 
command words are expected to be fixnums. The fixnum data (32 bits) for each 
command is described in this section. 

The format of the first word of each command is as follows, described by byte 
specifiers in the sys package: 

%%audio-command-op 

A 4-bit opcode selecting the action to be performed by the audio 
microcode. Each of the currently assigned opcodes is described 
elsewhere. See the section "Audio Command Opcodes", page 323. 
See the section "Polyphony Command Opcodes", page 326. 

%%audio-command-arg 

A 28-bit quantity, whose meaning differs for each opcode. When 
the contents of this field, known as the operand, is described as 
an address, it must be a physical address. The usual way to 
obtain such a physical address is via the function 
si:%vma-to-pma (which does a virtual-to-physical translation). 
This function is given a fixnum virtual memory address. The 
usual way to derive such addresses, which are usually references 
to array element cells, is via the %pointer and aloe functions. A 
physical address computed from a virtual address in this way 
cannot be validly used unless the relevant virtual address has been 
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wired in advance. See the section "Notes on Wired Structures", 
page 327. 

33.3.1 Audio Command Opcodes 

These are the valid opcodes of audio commands, with the exception of those 
commands associated with the polyphony feature. See the section "The Polyphony 
Feature", page 324. The descriptions tell what action is performed by the audio 
microtask when a command having this opcode is encountered by the microtask. 
The opcodes are listed under the the name of the system constant (also in the sys 
package) that gives the opcode value. 

%audio-command-stop 

Causes the audio microtask to halt execution. No more commands 
are fetched, or samples sent to the console, until the next 
execution of the sys:%audio-start instruction. The operand is 
ignored. 

%audio-command-jump 

Causes the audio microtask to fetch its next instruction not from 
the next sequential location, but from the physical address that is 
the value of the operand. Sequential execution of commands 
continues at that physical address. 

%audio-command-load-repeat 

Loads the repeat register with the value of the operand. The 
operand is an unsigned 28-bit number to be loaded into the repeat 
register, not an address. See the description of the 
%audio-command-loop opcode for the use of this register. 

%audio-command-loop 

Decrements the repeat register by 1. If the result is greater than 
zero, the operand is interpreted as a jump address, and execution 
of commands continues at that address, as with 
%audio-command-jump. Otherwise, if the result is less than or 
equal to zero, command execution continues with the next 
sequential command. 

%audio-command-samples 

Designates a vector of sample pairs to be sent to the console. The 
operand is the physical address of the first sample pair; the 
remaining samples are fetched from successive words of physical 
memory. The word in the command stream after the 
%audio-command-samples command contains a fixnum that is 
the count of the number of sample pairs to be fetched and sent to 
the console before the execution of %audio-command-samples 
terminates, and the microtask proceeds to the next sequential 
command. The %audio-command-samples command is thus a 
two-word command. 
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%audio-command-zero 

A synchronization primitive. The operand is the physical address 
of a cell, usually an array element. The audio microcode stores a 
fixnum zero in that cell as the result of executing the command 
having the opcode %audio-command-zero. The software can 
use this facility to test if the audio microtask has passed a given 
point in its command list. This enables the software to ascertain 
when it is safe to unwire or reuse data structures containing 
audio commands and/or samples. It is important to remember 
that the audio task, when active, locks out Lisp execution until it 
either sends a sample or goes idle. For example, if 
%audio-command-zero is immediately followed by 
%audio-command-stop, the observation of the zeroed cell by 
Lisp software implies that the microtask has already read, 
interpreted, and executed the %audio-command-stop. 

%audio-command-immediate 

Designates a vector of sample pairs to be sent to the console. 
Unlike %audio-command-samples, the sample pairs appear in 
the command list, in consecutive physical memory locations 
immediately following the the %audio-command-immediate 
command word. The operand of %audio-command-immediate 
is a number, which is the count of sample pairs. That number of 
sample pairs is fetched from the command list and sent to the 
console, one every 20 microseconds (at a 50 KHz sampling rate). 
Execution of the command list proceeds with the next command 
after the vector of sample pairs, after all samples have been sent 
to the console. 

It is critically important that the operand is equal to the number 
of samples provided, lest commands be interpreted as samples or 
vice versa. 



33.4 The Polyphony Feature 

Note: The polyphony feature is experimental in Release 6.0. It might be radically 
altered in function and/or interface in future releases, or might be removed entirely. 

The polyphony feature of the 3600 audio microcode provides a way to generate 
polyphonic music in real time. There is no need to precompute the samples and 
store them before playback from disk. The polyphony feature can produce six voices^ 
where a voice is a rhythmically independent sequence of musical notes. Each voice 
can be assigned a predefined, programmer-specified waveform, which determines the 
spectrum and the amplitude of the notes that appear in that voice, regardless of 
their pitch (frequency). The waveform specification determines the shape and 
amplitude of one cycle only of the waveform. This waveform is repeated at different 
frequencies to produce musical tones. 
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The polyphony feature is not intended as a general-purpose music synthesis facility. 
For example, no control over the amplitude envelopes (attack, decay, and so forth) of 
the sounds produced is provided. The polyphony feature is intended for use in music 
system prototyping, that is, composition research, music editing programs, and so 
forth. Nevertheless, the square-envelope notes it produces are not very different 
from those produced by some electronic organs. When properly programmed and 
amplified, the digital audio facility is capable of reasonably authentic performance of 
much of the organ literature. 

33.4.1 Operation of Polyphony 

The basic function of the polyphony feature is to generate, in parallel, six separate 
wave signals, usually of different frequencies, and sum them, at the sampling times 
of the audio facility. The audio microcode accomplishes this by maintaining, for each 
voice, a wavetable, a wavetable cursor, and an increment. 

The wavetable for each voice consists of 1024 fixnums stored in consecutive locations 
in physical memory, defining the waveform for notes in that voice. (Note: the size 
of the wavetables might change in a future release.) The fixnums constitute wave 
values, which digitally describe the waveform of the voice. 

The detailed interpretation of the wave values is as follows: Each fixnum wavetable 
element is interpreted as the algebraic sum of the wave values for the channels 
and 1, channel 1 having been shifted 16 bits left. In detail, the value for channel 
is a 32-bit signed (31 bits and sign, 2's complement) value between -2**15 and 
2**15-1, inclusive. The value for channel 1, also in the range -2**15 to 2**15-1, is 
shifted left 16 bits and added algebraically to the value for channel 0. The resulting 
number (which is always a fixnum) is the value of the wavetable entry. Note that 
this is not the same format as that of audio samples used by other parts of the 
audio facility. 

When polyphony is running (that is, when the audio microtask is interpreting the 
command %audio-command-polyphony), one value from each of the six tables is 
extracted, and these values are added algebraically. The resulting value is then 
offset by 2**15 in each halfword, and the resulting two halfwords are sent as audio 
samples to the two audio channels. 

You must ensure that the sum of the values from each table never exceeds the 
range -2**15 to 2**15-1 for either channel. The audio microcode clips or overflows 
into the other channel if this range is exceeded. 

Associated with each voice is also a counter/pointer called the wavetable cursor. This 
quantity is a 32-bit unsigned number. The high-order ten bits of the wavetable 
cursor for each voice constitute an index, which selects the entry of its wavetable to 
be summed into the audio sample to be produced. The low bits are used to measure 
the passage of time, overflowing into the high bits 1024 times per cycle of that voice. 

Also associated with each voice is a quantity called an increment. The increment is 
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a 32-bit fixnum. It controls the frequency, or pitch, of the note in each voice, by 
controlling the rate of incrementing of the wavetable cursor for that voice. When 
the command %audio-command-polyphony is being interpreted by the audio 
microtask, the increment for each voice is added to the wavetable cursor for that 
voice, and the resulting quantity is made the new wavetable cursor. (This addition 
is performed after the wavetable sample is extracted). Thus, when this repeated 
addition produces enough change in the value of the wavetable cursor such that the 
top ten bits are affected, a different wavetable entry for that voice is fetched at the 
next sampling time. Note that continued incrementing in this manner "wraps 
around". In this way, the wavetable cursor is way reset to the beginning of the 
wavetable, after the last entry in the wavetable has been used. 

The following function (available in the audio package) computes the increment for 
a voice from the frequency: 

(defun frequency-polyphonic-increment (frequency) 
(round (* frequency (float 1_32.)) audio:*sample-rate*)) 

You simultaneously establish the increment and wavetable location for a voice by the 
audio command %audio-command-load-voice. You instruct the polyphony facility 
to output samples by the audio command %audio-command-polyphony. This 
command uses all of the wavetables and increments previously established by 
%audio-command-load-voice, and outputs as many samples as requested, one 
every 20 microseconds, generated by summing entries from the six wavetables, 
incrementing the six wavetable cursors by the six associated increments as each 
sample is generated. 

Note: changing the wavetable and/or increment for a voice does not affect any other 
voice in any way. Since the audio microtask is awakened by an external timer, and 
runs until it either outputs a sample pair or stops, no discontinuity in notes played 
by other voices is observed when %audio-command-load-voice is interpreted to 
change the note in one voice. 

33.4.1.1 Polyphony Command Opcodes 

%audio-command-load-voice 

Establishes a wavetable and increment for one voice of the 
polyphony feature The operand is the physical address of the base 
of the wavetable for the voice. The word in the command stream 
after %audio-command-load-voice is, in its 32 data bits, the 
increment for the voice. The low three (that is, the least 
significant) bits of this increment are the binary number of the 
voice whose wavetable and increment are to be established. 
%audio-command-load-voice is effectively a two-word command. 

When polyphony is being performed, the audio microcode uses, for 
each voice, the wavetable and increment established for that voice. 
There is no way to assert that a voice does not exist, or has no 
wavetable, or no increment. A valid wavetable and increment 
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must be established for each of the polyphonic voices before 
%audio-command-polyphony is executed by the audio 
microcode, regardless of whether that voice is needed for the 
performance of the particular composition. 

%audio-command-load-voice does not affect the value of the 
wavetable cursor for the voice involved. 

%audio-command-polyphony 

The operand is an unsigned 28-bit number. The audio microcode 
sends out that many samples, one each 20 microseconds, 
generated from the currently established wavetables of the 
polyphony feature. The wavetable cursors of each voice used by 
the polyphony feature are incremented by the increment 
established for that voice as each sample is sent out. The values 
of the increments and the wavetable cursors are not reset in any 
way by either the start of %audio-command-polyphony, or its 
completion. 



33.5 The Beep Feature sys:%beep 

sys:%beep now works on 3600-family consoles that support the digital audio 
facilities. sys:%beep generates tones. The arguments, half-wavelength, (in 
microseconds) and duration, are compatible with the version of sys:%beep that ran 
on the Symbolics LM-2 computer. In the following example, a 440 Hz tone is 
generated for 50 milliseconds. 

(sys:%beep (// 1000000. 440. 2) 50000.) 



33.6 Notes on Wired Structures 

The audio microtask fetches commands from sequential locations of physical memory. 
Branch addresses in the command list are physical addresses. Audio sample data 
pointed to by the command list are also described by physical address. Wavetables 
used by the polyphony feature are also described and accessed by physical address. 

The audio microtask does not perform virtual address translation. Thus,, the 
command list and sample data must be stored in data structures wired, or locked, in 
main memory. That is, they must be prevented from being paged out or moved by 
the Lisp Machine operating system. As a digital audio programmer, you must 
therefore be aware of page boundaries. 

Audio command lists and sample vectors must be stored in wired pages consecutive 
in main memory, or scattered throughout main memory. If commands are stored in 
pages scattered throughout main memory, jumps must be programmed at the end of 
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each page, to send the audio microcode on to the next page. If sample vectors are 
stored in pages scattered throughout main memory, you must use a separate 
%audio-command-samples command to describe the samples on each page. 
Wavetables for the polyphony feature must be in consecutive locations in main 
memory. 

It is conventional to use Lisp arrays as the data structure containing audio 
commands, samples, and wavetables. Any type of array is usable for this purpose. 
art-q arrays allow one audio command or sample pair per element, and are also the 
only type of array whose elements can validly be addressed by the aloe function. 

33.6.1 Lisp Primitives for Wiring Memory 

The relevant Lisp primitives to wire data structures for the digital audio facility are 
sirwire-structure, si:wire-words, and si:wire-consecutive-words. 
si:wire-words wires any extent of virtual memory into physical memory, although 
the page frames into which successive pages are wired cannot be contiguous. 
si:wire-consecutive-words also wires any extent of virtual memory into physical 
memory, but successive pages are guaranteed to be stored in successive page frames 
in physical memory, sirwire-structure wires an entire structure (a convenience 
device to avoid having to calculate the location and extent of the virtual memory 
occupied by a structure) in the manner of si:wire-words. 

Since commands must be stored in consecutive locations in physical memory, 
si:wire-consecutive-words suggests itself as the natural primitive for this 
application. However, success of this primitive depends on the availability of 
consecutive page frames of main memory not already containing wired pages, and it 
is thus less likely to succeed as more pages are wired. Use of si:wire-structure and 
si:wire-words for audio data does not encounter this problem, but requires explicit 
programmer handling of page boundaries, as outlined previously. 

%find-structure-header and %structure-total-size are used to find the virtual 
memory location and extent of whole arrays or other structures to be wired. 
si:page-array-calculate-bounds can be used to calculate the virtual memory 
location and extent of portions of array that are to be be wired, when 
si:wire-words or si:wire-consecutive-words is used. %pointer-difference can 
also be used to determine the length of the extent, in words, between two addresses 
obtained via these primitives or the aloe function. 

Structures, or portions thereof, wired by any of these primitives, should be unwired 
by shunwire-structure or si:unwire-words (as appropriate) only after it has been 
ensured (via the techniques described) that the audio microtask is not fetching 
commands or samples from these structures. 
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34. Lisp Primitives for the Digital Audio Facilities 



34.1 Functions, Variables, and Macros for Digital Audio 

This section describes the functions, variables, and macros available to the Lisp 
Machine programmer to aid in programming the 3600 Digital Audio Facilities. All of 
these objects are tools for programming the audio microtask. Therefore, this section 
assumes that you already understand the microcode capabilities. See the section 
"Microcode Support for the Digital Audio Facilities", page 321. 

All of the digital audio functions, variables, and macros appear in the audio package. 
Several comprehensive examples of their use are provided in the file 
sys:examples;audio-examples.lisp. See the section "Examples of Using the Audio 
Facilities", page 339. 

These Lisp tools assume the existence of an audio command array, in which audio 
microtask commands are placed, and out of which they are executed by the audio 
microtask. A macro (audio:with-audio) manages the wiring and unwiring of 
command arrays within the scope of a program. 

A default audio command array is provided as part of these audio support primitives. 
All of these primitives, however, allow the specification of any suitable user-provided 
array as a command array. Such an array must be a nonindirect, single-dimensional 
art-q array, with a fill pointer, allocated in a static area (such as 
audio:audio-area). 

Command arrays, as all arrays, are finite in extent. Carefully planned 
synchronization techniques must be utilized to allow uninterrupted sound to be 
produced from a single command array that is being serially reused for sequences of 
audio commands. See the section "Examples of Using the Audio Facilities", page 
339. 



34.2 Digital Audio Parameters 

These are the critical constants of the audio facility. In programs these constants 
should be used instead of the numbers that are their current values in order to 
accommodate future modification of the audio facility. 

audio:*sample-rate* Variable 

The number of times per second that an audio sample is output when the 
audio microtask is active. This is a single-precision floating-point number. Its 
current value is 50e3, as determined by the hardware. 
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audio:*number-of-polyphonic-voices* Variable 

The number of polyphonic voices defined by the (experimental) polyphony 
feature. See the section "The Polyphony Feature", page 324. This is a 
fixnum, and its current value is 6. 



34.3 Testing for the Existence of Audio 

audio:audio-exists Variable 

This variable has a value of other than nil if and only if the machine on 
which it is evaluated has an operational audio facility. 



34.4 The Audio Wrapping Form 

audiorwith-audio &optional command-array &body body Macro 

Encases code that generates audio commands. It prepares a command array 
for use by wiring it in an appropriate fashion and unwires it when the body 
of the form is exited. When exited, it also unconditionally halts the audio 
microtask, silencing the audio output. 

If command-array is given as nil, the default command array is used. 

When the scope of audio:with-audio is entered, it also zeroes the fill 
pointer of the supplied command array. The various interface functions 
described later utilize the fill pointer of the command array to keep track of 
the current position in the audio command list being built. 
audio:with-audio also globally binds scheduler parameters to allow the 
process generating audio commands to gain control when necessary and more 
rapidly than usual. 



34.5 Building Audio Command Lists 

The functions listed in this section prepare arguments for, build, and store audio 
commands in a command array. They assume that the fill pointer of the array 
describes the next available location in the array, and they update the fill pointer as 
needed. The array must be wired, as some of these functions compute and store 
physical addresses of locations in the command array. Calling these functions does 
not produce sound. Sound is produced when the audio facility is directed (via 
audio:audio-start) to a command list produced by calling these functions. 

The fill pointer of the array defines a logical pointer called the audio index. The 
function audio:audio-index (which defines a location accessible with setf) is used to 
access this index (for example, for use as an argument to a later function call). 
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The current implementation uses command arrays that are wired into successive, 
contiguous page frames of physical memory. (Note: This might change in the 
future.) The exclusive use of these primitives hides this implementation detail. In 
order to accommodate future changes in this strategy, do not perform calculations on 
audio indices. Instead, request them whenever needed via audio:audio-index, and 
use them only as arguments to the primitives provided. 

Use of the macro audio:with-audio is the recommended way to establish the 
proper context in which these functions can be validly used. Each of them takes an 
optional argument, which specifies the command array in question. This argument 
always defaults to the facility's default command array. 

audio:audio-index &optional command-array Function 

This function returns the audio index for the next command to be stored in 
the command array in question. The form (audio:audio-index) is suitable 
for use as the first operand of a setf form. 

audio:audio-room &optional command-array Function 

This function returns the amount of available (unallocated) space, in single 
words, in the current command array. 

audio:audio-limit &optional command-array Function 

Returns a number one greater than the audio index of the last usable 
location in the command array. 

audio:audio-push-audio-stop &optional command-array Function 

Pushes a %audio-command-stop onto the command list in the command 
array. ("Push", as used in the names of these interfaces, means "add to the 
end of, at the current audio index, and increment the audio index 
appropriately."). 

audio:push-audio-jump target-index &optional command-array Function 

Pushes a %audio-command-jump onto the command list in the command 
array. The argument target-index is expected to be an audio index into the 
same command array, obtained previously from audio:audio-index. 

audio:push-audio-zero-flag flag-index &optional command-array Function 

Pushes a %audio-command-zero onto the command list in the command 
array. The argument flag-index is expected to be an audio index, into the 
same command array, of a "flag". Such flags are allocated, and their indices 
returned, by audio:reserve-audio-flags. 

audio:push-audio-load-voice voice-number wave-array Function 

wave-array-start-time 
wave-array-index-increment &optional 
command-array 
Pushes a %audio-command-load-voice onto the command list in the 
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command array, voice-number is a number, zero or greater, below the value 
of audio:*number-of-polyphonic-voices*, that specifies which polyphonic 
voice is to have its wavetable and increment loaded by the command to be 
built and stored, wave-array-index-increment is the value of that increment, 
which can be computed from the frequency of the tone desired by use of the 
function audiorfrequency-polyphonic-increment. The wavetable for the 
voice is expected to be in the art-q array wave-array. The argument 
wave-array-start-index is the index into that array where the 1024-word, 
wired, contiguous in physical memory, wavetable begins. 

audio:push-audio-polyphony number-of-samples &optional Function 

command-array 
Pushes a %audio-command-polyphony onto the command list in the 
command array. The argument number-of-samples specifies the sample count 
for the command to be built and pushed. 

audio:modify-audio-command-arg new-arg arg-type command-index Function 

&optional command-array 
Modifies an audio command that has already been pushed in the command 
array specified. This function must be used with extreme care: it can easily 
create invalid audio programs, which can destroy machine integrity. It 
modifies the 28-bit argument in the first word of the command whose index 
into the command array (command-index) is given. To be sure that this 
command can be validly used, read the description of the format of the 
individual audio command. See the section "Microcode Support for the Digital 
Audio Facilities", page 321. new-arg is the new value of the command whose 
index is given. The argument arg-type describes how it is converted to a 28- 
bit value for insertion in the existing command: 

immediate 

No processing is done, new-arg is expected to be a non-negative fixnum, 
which must be a count. 

:index 

The argument is an audio index into the command array specified. The 
location of the corresponding array cell is computed, verified to be wired, and 
the physical address of that location stored in the command. 

location 

The argument is a locative into a wired array of audio commands. The fact 
that this location is wired is verified, and the corresponding physical address 
stored in the command. 
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34.6 Storing Samples 

The functions and macros described in this section place audio sample pairs into the 
command program. These commands can be either immediate 
(%audio-command-immediate) or stored elsewhere (% audio-command-samples). 

audiorpush-array-of-audio-samples array &optional from to Function 

command-array immediate-p 
Pushes appropriate commands onto the command list in the command array 
specified, to output all the sample pairs in the array array between indices 
from and (up to but not including) to. from defaults to 0, and to to the 
active length of array, array must be an art-q array containing precomputed 
sample pairs. 

If immediate-p is non-nil, the data are copied into the command array, and 
output by means of %audio-command-immediate. 

If immediate-p is nil, array is assumed (and checked) to be wired, and as 
many %audio-command-samples commands as necessary to describe the 
data to be output are built and pushed, array need not be wired in 
contiguous page frames. 

audio:computing-immediate-audio-samples (count &optional Macro 

command-array) &body body 
Facilitates the storing of immediate audio sample pairs. The code it wraps, 
body, is responsible for generating immediate audio sample pairs: it does so by 
calling the macro audio:push-immediate-audio-sample, within the scope of 
the use of audio-.computing-immediate-audio-samples. Each use of 
audio:push-immediate-audio-sample stores one sample. The macro 
audio:computing-immediate-audio-samples arranges for an appropriate 
%audio-command-immediate to be constructed to describe all the samples 
stored. If the argument count is non-nil (at run time), it is expected to be a 
fixnum, which is the number of values to be stored. 

audio:computing-immediate-audio-samples checks, when it is exited, that 
that is the actual number of values stored, and signal an error if not. If 
count is nil, no checking is done, and 

audio:computing-immediate-audio-samples assumes that the number of 
samples that have been pushed is the correct number, and modifies the 
commands it builds appropriately. 

audio:push-immediate-audio-sample sample Macro 

Stores one audio sample pair, which is the value of its argument. This macro 
can be used validly within the scope of 
audio:computing-immediate-audio-samples. 
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34.7 Looping Through Audio Command Lists 

These two macros facilitate the use of %audio-command-loop to create loops in 
audio command lists. Keep in mind that the audio microcode does not support 
nested loops. 

audio:audio-loop (repeat-count-or-nil &optional command-array) Macro 

&body body 
This macro builds a loop (with %audio-command-loop and 
%audio-command-load-repeat) in the audio command list in the command 
array specified. The code, body, which is wrapped by this macro pushes 
commands for the body of the loop. The macro generates the audio 
command to loop back at the time its scope is exited. The argument 
repeat-count-or-nil , when non-nil, specifies how many times the loop is to be 
executed by the audio microtask. That is the number that is loaded into the 
repeat register. If repeat-count-or-nil is nil (at run time), the wrapped code 
must compute the number of loop repetitions, and invoke the macro 
audiorset-audio-repeat-count, whose argument is that number, some time 
before the scope of audio:audio-loop is exited. A diagnostic is issued (at 
run time) if the macro's scope is exited without the repeat count having been 
specified by one of these two means. 

audiorset-audio-repeat-count count Macro 

Sets the value count as the repeat count for an audio command list loop that 
is currently being built by audioraudio-loop. This macro can be validly 
used only within the scope of audio:audio-loop. 



34.8 Synchronization Flags 

These functions allocate, in the command array specified, locations to be used as 
synchronization flags (for %audio-command-zero), and allow the flags to be waited 
for and reset. The "reset", or "normal", state of these flags, is non-zero. The audio 
microcode "sets" them, by setting them to zero, when a %audio-command-zero is 
executed. By means of these flags, the real-time progress of the audio microtask can 
be monitored. 

audio:reserve-audio-flags count &optional command-array Function 

Allocates, in the command list currently being built in the command array 
specified, count locations to be used as audio flags. The flags are reset. A 
%audio-command-jump is inserted in the command list being constructed, 
so that the audio microtask jumps around the locations being used as flags. 
The return value of this function is the index, in the command array given, 
of the first of the flags allocated. You can assume, if more than one flag was 
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allocated by a call to audio:reserve-audio-flags, that the indices of flags 
other than the first are the sequential integers above the value returned. 

audio:wait-for-audio-flag flag-index &optional who-state audio Function 

reset-flag t command-array 
Waits for the audio flag specified by flag-index, in the command array 
specified, to be set. Normally, it is the audio microtask that sets these flags, 
by means of %audio-command-zero. whostate is the state to be displayed 
in the status line. If reset-flag is given as nil (this is not the default), the 
flag is not reset. The resetting, when requested, is performed after the flag 
has been observed to be set. The indices given to audio:wait-for-audio-flag 
should be those obtained from audio:reserve-audio-flags. 



34.9 Starting and Stopping the Audio Microtask 

These functions are used to start and stop the audio microtask. 

audio:audio-start index &optional command-array Function 

Starts the audio microtask, via the instruction sys:%audio-start, at the 
audio command specified by index in the command array specified. The 
array must be wired, and contain a valid, wired, audio command list. 

audio:audio-stop &optional command-array Function 

Stops the audio microtask immediately, causing immediate silence. 
audio:audio-stop accomplishes this by storing a %audio-command-stop 
instruction at location zero (0) of the command array given, and issuing 
audio:audio-start at that command. Thus, audio:audio-stop is 
destructive to the command array, and requires that it be wired. 



34.10 Conversions Between Sample Formats 

The following functions encode and decode sample pairs. They are provided to hide 
the internal representation of sample pairs. Some of these "functions" are actually 
implemented as macros to help make code that prepares audio samples as fast as 
possible. 

These functions convert between three formats of samples, float , fixnum y and 
sample. Float and fixnum formats describe channel values. Sample format is the 
actual format of sample pairs stored in command arrays and sample arrays. 

Fixnum format consists of integers in the range -1**15 s x < 1**15. Float format 
consists of floating numbers and float channels are in the range -1.0 * x < 1.0. 
You must ensure that a float format value is never +1.0. 
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audio:float-channei-fix float Function 

Converts a float format value to fixnum format. 

audio:fix-channe!-float fix Function 

Converts a fixnum format value to float format. 

audiorfix-sample right &optional left right Function 

Takes one or two fixnum format values for the two channels and returns a 
sample pair in sample format containing those two values. 

audiorfloat-sample right &optional left right Function 

Takes one or two float format values for the two channels and returns a 
sample pair in sample format containing those two values. 

audio:sample-channels sample Function 

Takes a sample pair in sample format and returns two values, the right and 
left channel values of that sample, respectively, in fixnum format. 

audio:sample-add-fix sample right-increment &optional left-increment Function 

right-increment 
Takes a sample pair and one or two increments, which are expected to be in 
fixnum format. The two channels of the sample pair are incremented by the 
two increments, and a new sample pair so constructed is returned. If the 
right channel goes out of range, it overflows into the left channel instead of 
clipping. 

audio:sample-add-float sample right-increment &optional Function 

left-increment right-increment 
Takes a sample pair and one or two increments, which are expected to be in 
float format. The two channels of the sample pair are incremented by the 
two increments, and a new sample pair so constructed is returned. If the 
right channel goes out of range, it overflows into the left channel instead of 
clipping. 

audio:sample-add-sampIe samplel sample2 Function 

Takes two sample pairs, in sample format, and produces a new sample pair 
by adding them. The operation performed is the addition of the fixnum 
format values corresponding to the channel values in the sample pairs. In 
other words, it is as if audio:sample-add-sample extracted the sample 
values from the sample pairs using audio:sample-channels, then added the 
channel values and reconstructed a sample pair using audiorfix-sample. 
The actual operation of audio:sample-add-sample is considerably more 
efficient. 
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34.11 Conversions for the Polyphony Feature 

These functions convert between fixnum and float format channel values and the 
values stored in wavetables used by the polyphony feature. See the section "The 
Polyphony Feature", page 324. 

audio:fix-polyphonic-wave-table-entry right &optional left right Function 

Takes one or two channel values in fixnum format and returns a fixnum 
representing those two values, in the format used in wavetables. This is not 
the same as sample format. 

audio:float-polyphonic-wave-table-entry right &optional left right Function 

Takes one or two channel values in float format and returns a fixnum 
representing those two values, in the format used in wavetables. This is not 
the same as sample format. 

audio:polyphonic-wave-table-entry-channels entry Function 

Takes as an argument an entry from a polyphonic wavetable, and returns 
two values in fixnum format, the right and left channel values encoded 
therein, respectively. 



34.12 Computing Polyphonic Increments 

This function computes the appropriate wavetable increment to specify the 
frequencies in polyphonic textures. 

audio:frequency-polyphonic-increment frequency Function 

Computes an increment value suitable for use with 

%audio-command-load-voice. The increment produced corresponds to a 
frequency of frequency. That is, the increment returned causes the 
wavetable for the voice with which it is used to be scanned frequency times 
per second. 
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35. Examples of Using the Audio Facilities 



This chapter presents seven program examples that use the digital audio facilities, in 
both real-time and non-real-time synthesis applications. 



35.1 Sine Wave Example 

This example generates a sine wave at a specified frequency. 
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(defun sine-wave (frequency) 

(audio:with-audio () ;Set up the audio environment 

(let* ((start (audio: audio- index)) ;Get the current (starting) index 
(samples-per-cycle (systround audio:*sample-rate* frequency)) 
;; Spread out several cycles to get a more accurate 
;; frequency. Extra factor of 2 makes sure there is room, 
(number-of-cycles (max 1 (// (audioraudio-limit) samples-per-cycle 2))) 
;; Actual number of samples we are going to produce 
(number-of-samples (* samples-per-cycle number-of-cycles))) 
;; Make sure we have room to play this frequency 
(when (> (+ number-of-samples 2) (audio:audio-limit)) 
(f error "Frequency too low")) 

This form allows us to compute number-of-samples inline 
(as opposed to computing them in a separate array). If we 
didn't know how many samples we were going to produce we could 
supply NIL for number-of-samples and the form will keep track 
and adjust the command array when the form is exited. Since we 
do supply the number of samples, the form will check to make 
sure we supply exactly that many. This helps us to avoid writing 
incorrect audio programs. 
( audi o : computi ng- immedi ate-audi o-sampl es ( number-of-sampl es ) 
(loop for sample-number below number-of-samples 
as phase = 

This is the phase (angle) that is passed to sin 
to get the sine wave. (This will cons double-floats in 
systems where si:pi is a double-float.) 
(// (* 2 si:pi sample-number number-of-cycles) 
number-of-sampl es ) 
as sample = 

Take the sin of the phase. Also multiply it 
by something less than 1 so we never get a 
value of 1.0 (a restriction, see 
documentation). Take the resulting floating 
point number in the range [-1.0, +1.0) and 
create a 'sample.' 
(audiorfloat-sample (* (sin phase) 0.9)) 
do ;; Now actually push the sample into the command array. 
(audio:push-immediate-audio-sample sample))) 
All of the samples are computed and an appropriate command has 
been generated to output them. Now we cause a jump back to the 
beginning to keep the sound going. 
(audio:push-audio-jump start) 

;; The program is complete, we can now start the audio facility. 
(audio:audio-start start) 

When you've heard enough, just type anything, with-audio 
supplies code to turn off the audio facility when exited and do 
other bookkeeping, 
(tyi)))) 
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35.2 Sawtooth Wave Example 

This is roughly the same as sine wave, but instead produces a sawtooth and only 
generates one cycle for it. 

(defun saw-wave (frequency) 
(audio:with-audio () 
(let* ((start (audio:audio-index)) 

(samples-per-cycle (sysrround audio:*sample-rate* frequency))) 
(audio: computing- immediate-audio-samples (samples-per-cycle) 
(loop for sample-number below samples-per-cycle 
as value = 

;; create a sawtooth value in the range [-1.0,1.0). 
;; Note this can never be exactly 1.0 since 
;; sample-number never quite gets as large as 
;; samples-per-cycle. ° 

(- (// (* 2.0 sample-number) samples-per-cycle) 1.0) 
do (audio:push-immediate-audio-sample (audio: float-sample value))) 
(audio:push-audio-jump start) 
(audio:audio-start start) 
(tyi))))) 



35.3 Square Wave Example 

This example demonstrates yet another type of waveform: a square wave. The 
audio-loop form is also exemplified. 
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(defun square-wave (frequency) 
(audio:with-audio () 

(let* ((start (audio: audio- index)) 

(samples-per-cycle (sys: round audio:*sample-rate* frequency)) 
;; Compute the number of samples for the high value and 
;; low value. Divide them as evenly as possible, 
(samples-first-half (// samples-per-cycle 2)) 
(samples-second-half (- samples-per-cycle samples-first-half))) 
Create a loop that will repeat samples-first-half times. If we 
weren't sure how many times we want to repeat, we could specify 
NIL and then use set-audio-repeat-count to set the count, 
(audio: audio- loop (samples- first-half) 
;; Compute 1 value (the high value) for output. 
(audio:computing-immediate-audio-samples (1) 
(audio:push-immediate-audio-sample (audio:float-sample 0.9)))) 
;; Do the same for the second half, 
(audio: audio- loop (samples-second-half) 
(audio:computing-immediate-audio-samples (1) 
(audio:push-immediate-audio-sample (audio:float-sample -0.9)))) 
;; Jump back to the beginning so we get more than one cycle, 
(audio: push-audio- jump start) 
(audio:audio-start start) 
(tyi)))) 



35.4 Beep Example 

This is basically a modified square-wave. 

(defun %beep-ignoring-most-issues (frequency duration) 
(audio:with-audio () 
(let* ((start (audio:audio-index)) 

(samples-per-cycle (sys:round audio:*sample-rate* frequency)) 
(samples-first-half (// samples-per-cycle 2)) 
(samples-second-half (- samples-per-cycle samples-first-half))) 
;; Can't nest loops, so we have to do the outer loop with a jump 
;; and bash the location when time has elapsed, 
(audio -.audio- loop (samples- first-half) 
( audi o : computi ng- immedi ate-audi o-sampl es ( 1 ) 
(audio:push-immediate-audio-sample (audio: float-sample 0.9)))) 
(audio: audio- loop (samples-second-half) 
( audi o : computi ng- immedi ate-audi o-sampl es ( 1 ) 
(audio: push- immediate-audio-sample (audio: float-sample -0.9)))) 
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This is the tricky part. We need to put a jump to the 
beginning, but we need to know where it is so we can cause it 
to fall through. We also need a flag so we know when the audio 
has stopped so we can exit. If we simply exited without 
waiting, the with-audio form could turn off the sound prematurely, 
(let* ( ; ; get the index that we will eventually bash and put in a 
;; jump back to the start. 

(jump-index (progl (audio:audio-index) (audio:push-audio-jump start))) 
;; reserve (and reset) an audio flag, 
(flag-index (audio:reserve-audio-flags 1)) 
;; reserve-audio-flags puts in a jump command around the 
;; flags it reserves, so we could have gotten the 
;; fall-through index after pushing the jump command. 
;; Anyway, get the index of the fall-through location, 
(fall -through- index (audio:audio-index))) 
;; When we bash the jump command the microcode will jump to here 
;; instead, which will cause the flag to get zeroed and the 
;; audio facility to stop. Both events happen atomically as far 
; ; as Lisp can tell because no samples are output in the 
; ; intervening time, 
(audio: push-audio-zero- flag flag- index) 
(audio: push-audio-stop) 
; ; Start the audio 
(audio:audio-start start) 

;; Wait the appropriate number of microseconds, 
(loop with start-time = (sys:%microsecond-clock) 
until 

(* (%32-bit-difference (sys:%microsecond-clock) start-time) duration)) 
; ; Here is where we bash the argument of the jump command to 
;; instead jump to the fall -through code. 

(audio:modify-audio-command-arg fall-through-index :index jump-index) 
;; Wait for the microcode to get to the flag and stop before we exit. 
(audio:wait-for-audio-flag flag-index "XBEEP"))))) 



35.5 Non-real-time Synthesis Example 



Certain kinds of very high quality sound cannot be generated in real time (one 
sample computed every 20 microseconds). Small pieces (pieces that can fit in 
physical memory) can be computed and then played later. 
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(defun play-audio-sample-array 
(array &optional (from 0) (to (array-active- length array))) 
(audio:with-audio () 

;; with-wired-structure wires the structure on entry 
;; and unwires on exit. External sample arrays must be wired, 
(si :with-wired-structure array 
(let* ((flag- index (audio:reserve-audio-flags 1)) 
(start (audio:audio-index))) 
;; Cause the samples to be played. If we supplied a non-NIL 
;; immediate-p argument, we wouldn't have to wire the 
;; structure, since the samples would be put in the command 
;; array which is already wired. However, most command arrays 
;; are not very large and probably couldn't hold all the 
;; samples. It's a tradeoff. 

(audio:push-array-of-audio-samples array from to) 
;; When the microcode finishes the samples, cause it to clear 
; ; the flag and stop, 
(audio: push-audio-zero- flag flag- index) 
(audio: push-audio-stop) 
; ; Start it up and wait for it to finish. 
(audio:audio-start start) 
(audio:wait-for-audio-flag flag-index "Play samples"))))) 



35.6 Playing Large Pieces Example 

Larger pieces (those that are too big to fit in physical memory) can still be played. 
This program plays data that is stored on the FEP filesystem. Storage must be on 
the FEP filesystem for several reasons. The digital audio system must produce data 
at the rate of one sample every 20 microseconds (including all overhead). This is 1.6 
megabits per second, which is a small factor away from raw disk speed. After 
overhead, this is getting close to the limits of the system. The LMFS file system 
incurs too much overhead. Also, we cannot copy (as LMFS would try to do if we 
used :string-in into an array) and we cannot spend time wiring buffers (as we 
would need to do with LMFS if we used :read-input-buffer). 

The FEP filesystem allows us to do disk direct memory access (DMA) directly into a 
buffer that we can keep wired. We can also setup the audio facility to point to 
these buffers (using push-array-of-audio-samples) once so we do not have to do it 
often. 

The macro with-multi-disk-buffering takes care of multibuffering bookkeeping. 
The user decides how many pages to devote to each buffer and the number of 
buffers. Disk arrays (the buffers) are allocated and wired on entry and unwired on 
exit. 
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(defmacro with-multi -disk-buffering 

((npages nbuffers) (array-of -buffers size-of-each-buffer) &body body) 
"npages and nbuffers are inputs, array-of-buffers and size-of-each-buffer are outputs" 
*(let ((, array-of-buffers (make-array .nbuffers)) 
(, size-of-each-buffer (* , npages 288.))) 
(unwind-protect 
(progn (loop for .idx. below , nbuffers 

as .buffer. = (allocate-resource 'si :disk-array 

(+ , size-of-each-buffer 288.)) 
do (setf (aref , array-of-buffers .idx.) .buffer.) 
(si:wire-structure .buffer.)) 
,@body) 
(loop for .idx. below , nbuffers 

as .buffer. = (aref , array-of-buffers .idx.) 
do (when (si :structure-wired-p .buffer.) 

(si :unwi re-structure .buffer.)) 
(deallocate-resource 'si :disk-array .buffer.))))) 

The function play-disk-file is the workhorse. There are many "if we are fast 
enough" clauses in this example. As long as there is not much other activity 
(especially paging activity) we usually are fast enough. 

(defun play-disk-file (pathname) 

(setq pathname (fsimerge-pathnames pathname "FEP:>*.mus. newest")) 
;; get the FEP file opened. 

(with-open-file (file pathname rdirection :block 

:if-exists : overwrite 
:if-does-not-exist terror) 
;; These numbers were picked after much experimentation and tuning, 
(let* ((npages 40.) (nbuffers 8)) 
(audiorwith-audio () 
(with-multi -disk-buffering (npages nbuffers) (buffers buffer-size) 
;; allocate a flag for each buffer for synchronization, 
(let* ((flags (audio:reserve-audio-flags nbuffers)) 
(start (audio:audio-index))) 
build the audio program. Push each buffer as an array of 
samples and then cause the flag associated with the 
buffer to be zeroed, 
(loop for buffer below nbuffers 

do (audio:push-array-of-audio-samples (aref buffers buffer) 
buffer-size) (audio:push-audio-zero-flag 
(+ flags buffer))) 
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;; Loop back to the beginning. To play new data (if we are 
;; fast enough, there /will/ be new data in the buffers), 
(audio: push-audio- jump start) 

n-queued is the number of buffers filled with valid data 
that the microcode can use. (The microcode will use 
all of them, but if we are fast enough we can keep them full.) 
We fill up all the buffers and then start the audio facility. 
This is done by an interaction with need-to-start and n-queued. 
(There is also provision for small files.) When all the buffers 
are queued, we need to wait for the microcode to finish 
the next one before we can do disk dma into it. 
(loop with n-queued = 

with need-to-start = t 

with n-file-blocks = (sysrceiling (send file rlength) 1152.) 

with current-file-block = 

initially (format t "~&~F seconds~%" 

(// (* n-file-blocks 288.) audio:*sample-rate*)) 
as blocks-this-whack = 

This is the number of blocks to do this time 
around. It is at most the number of pages of 
buffering. It is also at most the number of 
blocks remaining in the file, 
(min npages (- n-file-blocks current-file-block)) 
for buffer-number = 

This is the current buffer number we are going 
to try to fill. It is gets incremented modulo 
the number of buffers. 
then (\ (1+ buffer-number) nbuffers) 
as flag-index = (+ flags buffer-number) 
do ;; If all the buffers are queued, or if the end of 
the file has been reached, wait for the 
microcode to finish the buffer and then count it 
as dequeued, 
(when (or (= n-queued nbuffers) (zerop blocks-this-whack)) 
(audio:wait-for-audio-flag flag-index "Play disk file") 
(decf n-queued)) 

If we have some blocks to queue, make sure the 
flag for this buffer is reset, read in the 
blocks from the FEP file, increment the block 
pointer into the file, and count another buffer 
as queued, 
(when (not (zerop blocks-this-whack)) 
(audio: reset-audio- flag flag- index) 
(send file :block-in current-file-block blocks-this-whack 

(aref buffers buffer-number)) 
(incf current-file-block blocks-this-whack) 
(incf n-queued)) 
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If the audio facility hasn't been started and 
all buffers are filled, start the audio facility 
(and remember we did start it), 
(when (and need-to-start 

(or (= n-queued nbuffers) 

(i current-file-block n-file-blocks))) 
(audio: audio-start start) 
(setq need-to-start nil)) 
until 

;; We are finished when nothing is queued and we are 
;; at the end of the file, 
(and (zerop n-queued) 

(2; current-file-block n-file-blocks))))))))) 



35.7 Polyphony Example 

This is a simple muse. It uses roughly the same multibuffering strategy as the disk 
example, so that portion will not be commented as heavily. (See the section "Playing 
Large Pieces Example", page 344.) The muse muses some number of voices (user 
specified) between 1 and 6. All voices start at DO (C). Each step (approximately 
every 1/4 second) causes each voice to wander randomly between 2 diatonic tones 
below the previous value and 2 diatonic tones above the previous value. 

;;; Figure out how large wave tables are in this release. 

( def const *sampl es-per-polyphon i c-wave- tabl e* 

(expt 2 (byte-size sys:%%audio-increment-integer))) 



This is the wave-array for the muse. 

It is big enough to ensure that there will be at least 

*samples-per-polyphonic-wave-table* consecutive wired words. 



(defvar *muse-wave-array* 

(make-array (+ *samples-per-polyphonic-wave-table* sys:page-size -1) 

:initial-value :area audio:audio-area)) 
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(defun polyphonic-muse (&optional (n-voices 4) &aux address wired) 
(check-arg n-voices (and (fixp n-voices) 

(s 1 n-voices audio:*number-of-polyphonic-voices*)) 
"an integer between 1 and 6") 
(audio:with-audio () 
(unwind-protect 
(let ((offset-to-page 

;; This is how one gets to the number of Qs 
;; to the beginning of a page boundary 
( ldb sys :%%vma-word-of fset 
(- sys: page-size 

(ldb sys :%%vma-word- offset 

(%po inter (locf (aref *muse-wave-array* 0)))))))) 
;;; Wire words of the wave table, starting at 
;;; the location computed above. 

(setq address (locf (aref *muse-wave-array* offset-to-page))) 
(si :wire-consecutive-words 
address ;where 

*samples-per-polyphonic-wave- table*) ;how many, one per word, 
(setq wired t) ;Set a reminder to unwire it. 
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Set up the muse wave array for a 1/6 (minus a bit) amplitude 
sinewave (sawtooth doesn't seem to sound good here). 1/6 
allows all six voices to proceed without overflow. The 
"minus a bit" avoids clipping at 1.0. 
(loop for index below *samples-per-polyphonic-wave-table* 

do (setf (aref *muse-wave- array* (+ index offset-to-page)) 
(audio: float-polyphonic-wave- table-entry 
(// (sin (// (* 2.0 si:pi index) 

*samples-per-polyphonic-wave-table*)) 6.2)))) 
Initialize each voice to a reasonable value. It is essential 
that each voice gets a proper wave-array pointer and 
increment value. An increment value of will cause the 
pointer never to be incremented. (This isn't strictly true, 
since the voice number is stored in the low 3 bits, but this 
advances the pointer very slowly.) 
(let ((start (audio:audio-index))) 
(loop for voice below audio:*number-of-polyphonic-voices* 

do 
(audio: push-audio- load-voice voice *muse-wave- array* offset-to-page 0)) 
(audio: push-audio-stop) 
(audio: audio-start start) 
;; put the audio index back to the start 
(setf (audio:audio-index) start)) 
(loop with nbuffers = 4 
with n-queued = 
with need-to-start = t 

with flags = (audio:reserve-audio-flags nbuffers) 
with start = (audio:audio-index) 
with chords-per-whack = 

Take the room remaining, divide by the level of 
buffering and then divide by the sum of [2 locations 
per voice for the push-audio-load-voice command, one 
for the push-audio-polyphony command, and one for a 
possible flag or jump]. 
(// (audio:audio-room) nbuffers (+ (* n-voices 2) 1 1)) 
with half-tone-offsets = 

(and the multiples of 12) are DO. The other 
numbers are offsets (from 0) to consecutive notes in 
the diatonic scale. 
'(-25. -24. -22. -20. -19. -17. -15. -13. 
-08. -07. -05. -03. -01. 
+04. +05. +07. +09. +11. 
+16. +17. +19. +21. +23. 
+24. +26. +28. +29. +31. +33. +35.) 
with half-tone-offsets- length = (length half-tone-offsets) 



-12. -10. 
000. +02. 
+12. +14. 
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with voice- indices = 

;; A list, one element for each voice, starting at middle DO. 
(make- list n-voices 

:initial-value (find-position-in-list 000. half-tone-offsets)) 
for buffer-number = then (\ (1+ buffer-number) nbuffers) 
until (kbd-tyi -no-hang) ; Stop when user hits a key 
do 
(when (* n-queued nbuffers) 
;; this also resets the flag 

(audio:wait-for-audio-flag (+ flags buffer-number) "Muse") 
(decf n-queued)) 
;; If this is buffer zero, make sure we are back to the start, 
(when (zerop buffer-number) 

(setf (audio:audio-index) start)) 
;; setup the chords for this buffer 
(loop repeat chords-per-whack 
do ;; update each voice 

(loop for voice-indices-scan on voice-indices 
as old-index = (car voice-indices-scan) 
as new- index = 

(let ((index (+ old-index (random 5) -2))) 
;; clip at the boundaries of the list 
(cond ((< index 0) 1) 

((* index half-tone-offsets-length) 

(- half-tone-offsets- length 2)) 
(T index))) 
do (setf (car voice- indices-scan) new- index)) 
;; And queue the new values to polyphony facility 
(loop for index in voice-indices 
for voice-number upfrom 

as half-tone-offset = (nth index half-tone-offsets) 
as octave-offset = (// half-tone-offset 12.0) 
as frequency- factor = (expt 2.0 octave-offset) 
as frequency = (* 256.0 frequency- factor) 
do (audio.-push-audio-load-voice 

voice-number *muse-wave-array* offset-to-page 
( audi o : f requency-polyphoni c- i ncrement frequency) ) ) 
; ; Do polyphony for 1/4 second 

(audio.-push-audio-polyphony (sysrround audio:*sample-rate* 4))) 
;; synchronize this buffer 

(audio:push-audio-zero-flag (+ flags buffer-number)) 
(incf n-queued) 

(when (and (;> n-queued nbuffers) need-to-start) 
(audio:push-audio-jump start) 
(audio:audio-start start) 
(setq need-to-start nil)))) 
(when wired 
(si :unwire-words address *samples-per-polyphonic-wave-table*))))) 
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PART VI. 



Dates and Times 
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36. Representation of Dates and Times 



The time package contains a set of functions for manipulating dates and times: 
finding the current time, reading and printing dates and times, converting between 
formats, and other miscellany regarding peculiarities of the calendar system. It also 
includes functions for accessing the Lisp Machine's microsecond timer. 

Times are represented in two different formats by the functions in the time 
package. One way is to represent a time by many numbers, indicating a year, a 
month, a date, an hour, a minute, and a second (plus, sometimes, a day of the week 
and time zone). The year is relative to 1900 (that is, if it is 1984, the year value 
would be 84); however, the functions that take a year as an argument will accept 
either form. The month is 1 for January, 2 for February, and so on. The date is 1 
for the first day of a month. The hour is a number from to 23. The minute and 
second are numbers from to 59. Days of the week are fixnums, where means 
Monday, 1 means Tuesday, and so on. A time zone is specified as the number of 
hours west of GMT; thus in Massachusetts the time zone is 5. Any adjustment for 
daylight saving time is separate from this. 

This "decoded" format is convenient for printing out times in a readable notation, 
but it is inconvenient for programs to make sense of these numbers, and pass them 
around as arguments (since there are so many of them). So there is a second 
representation, called Universal Time, which measures a time as the number of 
seconds since January 1, 1900, at midnight GMT. This "encoded" format is easy to 
deal with inside programs, although it doesn't make much sense to look at (it looks 
like a huge integer). So both formats are provided; there are functions to convert 
between the two formats; and many functions exist in two forms, one for each 
format. 

The Lisp Machine hardware includes a timer that counts once every microsecond. It 
is controlled by a crystal and so is fairly accurate. The absolute value of this timer 
doesn't mean anything useful, since it is initialized randomly; what you do with the 
timer is to read it at the beginning and end of an interval, and subtract the two 
values to get the length of the interval in microseconds. These relative times allow 
you to time intervals of up to an hour (32 bits) with microsecond accuracy. 

The Lisp Machine keeps track of the time of day by maintaining a "timebase", using 
the microsecond clock to count off the seconds. When the machine first comes up, 
the timebase is initialized by querying hosts on the local network to find out the 
current time. 

A similar timer counts in 60ths of a second rather than microseconds; it is useful for 
measuring intervals of a few seconds or minutes (or hours, which are longer than 
the microsecond timer's range) with less accuracy. Periodic housekeeping functions 
of the system are scheduled based on this timer. 
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37. Getting and Setting the Time 



time:get-time Function 

Get the current time, in decoded form. Return seconds, minutes, hours, 
date, month, year, day-of-the-week, and daylight-savings-time-p, with the 
same meanings as time:decode-universal-time. 

time:get-universal-time Function 

Returns the current time, in Universal Time form. 

time:set-local-time &optional new-time Function 

Set the local time to new-time. If new-time is supplied, it must be either a 
universal time or a suitable argument to timetparse. If it is not supplied, or 
if there is an error parsing the argument, you will be prompted for the new 
time. Note that you will not normally need to call this function; it is mainly 
useful when the timebase becomes unreliable for one reason or another. 



37.1 The 3600-family Calendar Clock 

Machines in the 3600 family have a calendar clock that operates independently of 
the other Lisp Machine timers. When you cold boot and the machine fails to get 
the time from the network, it asks you to type in the time. If the calendar clock 
has been set, it uses the calendar clock reading as the default for the time you 
specify. If the calendar clock has not been set, it offers to set it to the time you 
type in. See the function timednitialize-timebase, page 369. 

You can also set the calendar clock yourself using time:set-calendar-clock and read 
it using timerread-calendar-clock. 

time:set-calendar-clock new-time Function 

Sets the calendar clock to new-time, which must be either a universal time or 
a suitable argument to time:parse. Returns t if the calendar clock is set 
successfully, otherwise nil. 

time:read-calendar-clock &optional even-if-bad Function 

Attempts to read the calendar clock. If the attempt is unsuccessful, returns 
nil. If the attempt is successful and the time appears to be valid, returns 
the time in universal time form. If the attempt is successful but the time 
appears to be invalid, takes action depending on the value of even-if-bad: 

nil or unspecified Returns nil 

Not nil Attempts to convert the internal format to universal 
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time. If the conversion is successful, returns the time 
in universal time form. Otherwise, signals an error. 



37.2 Elapsed Time in 60ths of a Second 

Rather than calendrical date/times, the following functions deal with elapsed time in 
60ths of a second. These times are used for many internal purposes where the idea 
is to measure a small interval accurately, not to depend on the time of day or day of 
month. 

time Function 

Returns a number that increases by 1 every 1/60 of a second, and "wraps 
around" less than once a day. Use the time-lessp and time-difference 
functions to avoid getting in trouble due to the wraparound, time is 
completely incompatible with the Maclisp function of the same name. 

time-lessp timel time2 Function 

t if timel is earlier than time2> compensating for wraparound, otherwise nil. 
Also works for time:fixnum-microsecond-time values. 

time-difference timel time2 Function 

Assuming timel is later than time2, returns the number of 60ths of a second 
difference between them, compensating for wraparound. Also works for 
time:fixnum-microsecond-time values. 

time-increment time increment Function 

Adds increment to time and returns the resulting time value, compensating 
for wraparound, time should be a value of time, as returned by the time 
function, and increment should be an amount of time expressed as a fixnum 
in units of 60ths of a second. Also works for 
time:fixnum-microsecond-time values. 

time-elapsed-p increment initial-time &optional (final-time (time)) Function 

Returns t if at least increment 60ths of a second have elapsed between 
initial-time and final-time. Otherwise, returns nil. 

initial-time and final-time should be time values as returned by the time 
function, final-time defaults to the result of (time). 

Example: 

(defun process-sleep (interval &optional (whostate "Sleep")) 
(process-wait whostate #'time-elapsed-p interval (time))) 
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37.3 Elapsed Time in Microseconds 

time:microsecond-time Function 

Return the value of the microsecond timer, as a bignum. The values 
returned by this function "wrap around" about once per hour. 

time:fixnum-microsecond-time Function 

Return the value of the low 31 bits of the microsecond timer, as a fixnum. 
This is like time:microsecond-time, with the advantage that it returns a 
value in the same format as the time function, except in microseconds rather 
than 60ths of a second. This means that you can compare fixnum- 
microsecond-times with time-lessp and time-difference. 
time:fixnum-microsecond-time is also a bit faster, but has the 
disadvantage that since you only see the low bits of the clock, the value can 
"wrap around" more quickly (about every half hour). 
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38. Printing Dates and Times 



The functions in this section create printed representations of times and dates in 
various formats, and send the characters to a stream. To any of these functions, 
you may pass nil as the stream parameter, and the function will return a string 
containing the printed representation of the time, instead of printing the characters 
to any stream. 

time:print-current-time &optional (stream standard-output) Function 

Print the current time, formatted as in 11/25/83 14:50:02, to the specified 
stream. 

time:print-time seconds minutes hours day month year &optional Function 

(stream standard-output) 
Print the specified time, formatted as in 11/25/83 14:50:02, to the specified 
stream. 

time:print-universal-time ut &optional (stream standard-output) Function 

timezone 
Print the specified time, formatted as in 11/25/83 14:50:02, to the specified 
stream. 

time:print-current-date &optional (stream standard-output) Function 

Print the current time, formatted as in 

Friday the twenty-fifth of November, 1983; 3:50:41 pm, to the specified 
stream. 

time:print-date seconds minutes hours day month year Function 

day-of-the-week &optional (stream 

standard-output) 
Print the specified time, formatted as in 

Friday the twenty-fifth of November, 1983; 3:50:41 pm, to the specified 
stream. 

time:print-universal-date ut &optional (stream standard-output) Function 

timezone 
Print the specified time, formatted as in 

Friday the twenty-fifth of November, 1983; 3:50:41 pm, to the specified 
stream. 

time:print-brief-universal-time ut &optional (stream Function 

standard-output) (ref-ut 
(time:get-universal-time)) 
This is like time:print-universal-time except that it omits seconds and only 
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prints those parts of ut that differ from ref-ut, a universal time that defaults 
to the current time. Thus the output will be in one of the following three 
forms: 



02:59 
3/4 14:01 
8/17/74 15:30 



the same day 

a different day in the same year 

a different year 



format accepts some directives for printing dates and times. 
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39. Reading Dates and Times 



These functions accept most reasonable printed representations of date and time and 
convert them to the standard internal forms. The following are representative 
formats that are accepted by the parser: 

"March 15, 1960" "15 March 1960" "3//15//60" "3//15//1960" 

"3-15-60" "3-15" "15-March-60" "15-Mar-60" "March-15-60" 

"1960-3-15" "1960-March-15" "1960-Mar-15" 

"1130." "11:30" "11:30:17" "11:30 pm" "11:30 am" "1130" "113000" 

"11.30" "11.30.00" "11.3" "11 pm" "12 noon" 

"midnight" "m" "Friday, March 15, 1980" "6:00 gmt" "3:00 pdt" 

"15 March 60" "15 March 60 seconds" 

"fifteen March 60" "the fifteenth of March, I960;" 

"one minute after March 3, 1960" 

"two days after March 3, 1960" 

"Three minutes after 23:59:59 Dec 31, 1959" 

"now" "today" "yesterday" "two days after tomorrow" 

"one day before yesterday" "the day after tomorrow" 

"five days ago" 

The parsing functions accept date strings in ISO standard format. These strings are 
of the form "yyyy-mm-dd", where: 

yyyy Four digits representing the year 

mm The name of the month, an abbreviation for the month, or one or 

two digits representing the month 

dd One or two digits representing the day 

Following are some restrictions on strings to be parsed: 

• You cannot represent any year before 1900. 

• A four-digit number alone is interpreted as a time of day, not a year. For 
example, "1954" is the same as "19:54:00" or "7:54 pm", not the year 1954. 

• The parser does not recognize dates in European format. For example, 
M 3//4//85" or "3-4-85" is always the same as "March 4, 1985", never 
"April 3, 1985". A string like "15//3//85" is an error. In such strings, the 
first integer is always parsed as the month and the second integer as the day. 

time:parse string ^optional (start O) end (futurep t) base-time Function 

must-have-time date-must-have-year 
time-must-have-second (day-must-be-valid t) 
Interpret string as a date and/or time, and return seconds, minutes, hours, 
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date, month, year, day-of-the-week, daylight-savings-time-p, and relative-p. 
start and end delimit a substring of the string; if end is nil, the end of the 
string is used, must-have-time means that string must not be empty. 
date-must-have-year means that a year must be explicitly specified. 
time-must-have-second means that the second must be specified. 
day-must-be-valid means that if a day of the week is given, then it must 
actually be the day that corresponds to the date, base-time provides the 
defaults for unspecified components; if it is nil, the current time is used. 
futurep means that the time should be interpreted as being in the future; for 
example, if the base time is 5:00 and the string refers to the time 3:00, that 
means the next day if futurep is non-nil, but it means two hours ago if 
futurep is nil. The relative-p returned value is t if the string included a 
relative part, such as "one minute after" or "two days before" or "tomorrow" 
or "now"; otherwise, it is nil. 

time:parse-universal-time string &optional (start 0) end {futurep t) Function 

base-time must-have-time date-must-have-year 
time-must-have-second (day-must-be-valid t) 
This is the same as timerparse except that it returns one integer, 
representing the time in Universal Time, and the relative-p value. It also 
returns a third value, which is t if hours, minutes, or seconds were specified 
by string, or nil if they were not. 

time:parse-universal-time-relative date-spec reference-date-spec Function 

&optional (future-p t) 
Like time:parse-universal-time, except that date-spec is parsed relative to 
reference-date-spec. The returned values are the same as those of 
time:parse-universal-time. 

date-spec is a string suitable as the first argument to 

time:parse-universal-time. reference-date-spec is a universal-time integer or 
a string that can be parsed as an unambiguous time. If future-p is nil, an 
ambiguous date-spec is interpreted as being in the past relative to 
reference-date-spec, otherwise, it is interpreted as being in the future. The 
default for future-p is t. 

For example: 

(time:parse-universal-time-relative "5 pm" "today") 

returns the same value when evaluated anytime today, whether or not the 
current time is before or after 5 pm. 

time:parse-present-based-universal-time time-being-parsed Function 

Like time:parse-universal-time, except that missing components in 
time-being-parsed are defaulted to the beginning of the smallest unsupplied 
unit of time. The returned values are the same as those of 
time:parse-universal-time. time-being-parsed is a string suitable as the 
first argument to time:parse-universal-time. 
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For example, "5 pm" is parsed as 5 pm on the current day, whether the 
current time is before or after 5 pm. "Thursday" is parsed as Thursday of 
the current week, whether today is Wednesday or Friday. "1 June" is parsed 
as June 1 of the current year, whether the date is before or after June 1. 
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40. Reading and Printing Time Intervals 



Several functions read and print time intervals. They convert between strings of the 
form "3 minutes 23 seconds" and integers representing numbers of seconds. 

time:print-interval-or-never interval &optional (stream Function 

standard-output) 

Prints the representation of interval as a time interval onto stream. If 
interval is nil, it prints "Never", interval should be a nonnegative integer, or 
nil. 

time:par8e-interval-or-never string &optional start end Function 

string is the character-string representation of an interval of time, start and 
end specify a substring of string to be parsed; they default to the beginning 
and end of stringy respectively. The function returns an integer if string 
represented an interval, or nil if string represented "never". If string is 
anything else, an error occurs. Examples of acceptable strings: 

"4 seconds" "4 sees" "4 s" 

"5 mins 23 sees" "5 m 23 s" "23 SECONDS 5 M" 

"never" "not ever" "no" 

"" "3 yrs 1 week 1 hr 2 mins 1 sec" 

Note that several abbreviations are understood, the components can be in any 
order, and case (upper versus lower) is ignored. Also, "months" is not 
acceptable, since months vary in length. This function accepts anything that 
time:print-interval-or-never produces, and it returns the same integer (or 
nil). 

time:read-interval-or-never &optional (stream standard-input) Function 

Reads a line of input from stream (using readline) and calls 
time:parse-interval-or-never on the resulting string. 
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41. Time Conversions 



time:decode-universal-time universal-time &optional timezone Function 

Convert universal-time into its decoded representation. The following values 
are returned: seconds, minutes, hours, date, month, year, day-of-the-week, 
daylight-savings-time-p. daylight-savings-time-p tells you whether or not 
daylight savings time is in effect; if so, the value of hour has been adjusted 
accordingly. You can specify timezone explicitly if you want to know the 
equivalent representation for this time in other parts of the world. 

time:encode-universal-time seconds minutes hours day month year Function 

&optional timezone 
Convert the decoded time into Universal Time format, and return the 
Universal Time as an integer. If you do not specify timezone, it defaults to 
the current time zone adjusted for daylight saving time; if you provide it 
explicitly, it is not adjusted for daylight saving time, year may be absolute, or 
relative to 1900 (that is, 84 and 1984 both work). 

time:*timezone* Variable 

The value of time:*timezone* is the time zone in which this Lisp Machine 
resides, expressed in terms of the number of hours west of GMT this time 
zone is. This value does not change to reflect daylight saving time; it tells 
you about standard time in your part of the world. 
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42. Internal Time Functions 



These functions provide support for functions that deal with dates and time. Some 
user programs may need to call them directly, so they are documented here. 

For more information on functions that deal with dates and times: 

See the section "Getting and Setting the Time", page 355. 

See the section "Elapsed Time in 60ths of a Second", page 356. 

See the section "Elapsed Time in Microseconds", page 357. 

See the section "Printing Dates and Times", page 359. 

See the section "Reading Dates and Times", page 361. 

See the section "Reading and Printing Time Intervals", page 365. 

See the section "Time Conversions", page 367. 

time:initialize-timebase &optional ut {use-network t) Function 

Initializes the timebase. If ut, a universal-time integer, is supplied, uses ut as 
the current time. If ut is nil or unspecified and if use-network is not nil, 
queries local network hosts to find out the current time, (use-network is t by 
default.) If it cannot get the time from the network, or if ut and 
use-network are both nil, prompts the user for a string to parse as the 
current time. On machines in the 3600 family, if the calendar clock has 
been set, uses the calendar clock reading as the default time for the user to 
specify. If the calendar clock has not been set, offers to set it to the time 
that the user specifies. 

This is called automatically during system initialization. You may want to 
call it yourself to correct the time if it appears to be inaccurate or downright 
wrong. See the function time:set-local-time, page 355. 

time:daylight-savings-time-p hours day month year Function 

Return t if daylight saving time is in effect for the specified hour; otherwise, 
return nil. year may be absolute, or relative to 1900 (that is, 84 and 1984 
both work). 

time:daylight-savings-p Function 

Return t if daylight saving time is currently in effect; otherwise, return nil. 

time:month-length month year Function 

Return the number of days in the specified month; you must supply a year in 
case the month is February (which has a different length during leap years). 
year may be absolute, or relative to 1900 (that is, 84 and 1984 both work). 

time:leap-year-p year Function 

Return t if year is a leap year; otherwise return nil. year may be absolute, 
or relative to 1900 (that is, 84 and 1984 both work). 
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time:verify-date day month year day-of-the-week Function 

If the day of the week of the date specified by day y month, and year is the 
same as day-of-the-week y return nil; otherwise, return a string that contains 
a suitable error message, year may be absolute, or relative to 1900 (that is, 
84 and 1984 both work). 

time:day-of-the-week-string day-of-the-week &optional {mode Function 

':long) 

Return a string representing the day of the week. As usual, means 
Monday, 1 means Tuesday, and so on. Possible values of mode are: 

:short Return a three-letter abbreviation, such as "Mon", "Tue", and so 
on. 

:long Return the full English name, such as "Monday", "Tuesday", 

and so on. This is the default. 

medium Same as :short, but use "Tues" and "Thurs". 

tfrench Return the French name, such as "Lundi", "Mardi", and so on. 

:german Return the German name, such as "Montag", "Dienstag", and 

so on. 

ritalian Return the Italian name, such as "Lunedi", "Martedi", and so 

on. 

time:month-string month &optional {mode ':long) Function 

Return a string representing the month of the year. As usual, 1 means 
January, 2 means February, and so on. Possible values of mode are: 

rshort Return a three-letter abbreviation, such as "Jan", "Feb", and so 
on. 

:long Return the full English name, such as "January", "February", 

and so on. This is the default. 

medium Same as rshort, but use "Sept", "Novem", and "Decern". 

rfrench Return the French name, such as "Janvier", "Fevrier", and so 
on. 

:roman Return the Roman numeral for month (this convention is used in 
Europe). 

:german Return the German name, such as "Januar", "Februar", and so 

on. 

ritalian Return the Italian name, such as "Gennaio", "Febbraio", and so 

on. 
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time:timezone-string &optional (timezone time:*timezone*) Function 

(daylight-savings-p (time:dayligbt-savings-p)) 

Return the three-letter abbreviation for this time zone. For example, if 
timezone is 5, then either "EST (Eastern Standard Time) or "CDT" (Central 
Daylight Time) will be used, depending on daylight-savings-p. 
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PART VII. 
Zwei Internals 
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43. Introduction to Zwei Internals 



Zmacs, the Lisp machine editor, is built on a large and powerful system of text- 
manipulation functions and data structures, called Zwei. 

Zwei is not an editor itself, but rather a system on which other text editors are 
implemented. For example, in addition to Zmacs, the Zmail mail reading system also 
uses Zwei functions to allow editing of a mail message as it is being composed or 
after it has been received. The subsystems that are established upon Zwei are: 

• Zmacs, the editor that manipulates text in files 

• Dired, the editor that manipulates directories represented as text in files 

• Zmail, the editor that manipulates text in mailboxes 

• Converse, the editor that manipulates text in messages 

Since these subsystems share Zwei in the dynamically linked Lisp environment, 
many of the commands available as Zmacs commands are available in other editing 
contexts as well. 
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44. Stream Facility for Editor Buffers 



zwei:open-editor-stream opens a stream to an editor buffer; it is analogous to 
open for files. zwei:with-editor-stream also opens a stream to an editor buffer; it 
is analogous to with-open-file for files. 



44.1 The zwekwith-editor-stream Macro 

zwei: with-edi tor-stream (name options) body ... Macro 

zwei:with-editor-stream opens a bidirectional stream called name to a 
buffer, which is designated in one of the following ways: 

an interval 
a buffer name 
a Zwei window 
a pathname 

It takes the same keyword options as zwei:open-editor-stream. See the 
section "Keyword Options", page 378. On exit, it sends a :force-redisplay 
message to the stream, which causes the editor to do any necessary redisplay. 



44.2 The zwehopen-editor-stream Function 

zweiropen-editor-stream options Function 

zwei:open-editor-stream is used by zweirwith-editor-stream. You might 
sometimes need to call it directly for doing operations that need not be in the 
scope of a "with" form (for the same reasons that you would use open 
instead of with-open-files for file I/O). For example, you would use this in 
conjunction with with-open-stream-case for appropriate error signalling. 

It takes the same keyword options as zwei:with-editor-stream. See the 
section "Keyword Options", page 378. 

You can send a :force-redisplay message at any time while the stream is 
open. 
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44.3 Keyword Options 



zwei:with-editor-stream and zweiropen-editor-stream both recognize the same 
set of keyword options. Some of the options are mutually exclusive and some are 
interdependent. 

You specify where to find the text by using one of the following keywords, whichever 
is appropriate to the situation. The keywords appear here in priority order. When 
the options specify several of these, one from the top of the list overrides one from 
further down in the list, regardless of what order the keywords appear in the 
options list. 

rinterval 

:buffer-name 

tpathname 

rwindow 

:start 

The options refer to an object called a bp. This is a Zwei data structure for 
representing a particular position in a buffer. 



Option 
:buffer-name 



:create-p 



Values and meaning 

The full name of a buffer to use for the stream, 
(zwei :with-edi tor-stream 
(foo ' :buffer-name (send zwei .-^interval* * mame)) 

The buffer does not need to exist (see :create-p). The following 
example creates a Zmacs buffer named temp and opens the 
stream foo to it. 

(zwei :with-edi tor-stream (foo "temp") 

Specifies what to do when the buffer does not exist. This applies 
only in conjunction with :buffer-name or :pathname with 
:load-p. 

Meaning 



Value 

:ask 

terror 

t 
:warn 



Queries the user before creating the buffer. 

Signals an error and provides proceed types for 
creating it or supplying an alternate. 

Creates the buffer. 

Notifies the user that a buffer is being created 
(the default). 



rdefaults 



Specifies the pathname defaults against which a :pathname 
option would be merged. These are necessary in case reprompting 
needs to occur. The default is nil, meaning to use the default 
defaults. This option applies only in conjunction with :pathname. 
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:end 



Specifies the conditions for terminating the stream (the "end of 
file" condition). 

Meaning 

Stops when this buffer bp is reached. 



Value 

bp 

rend 



:mark 



:point 



Stops at the end of the buffer (the default). 
This applies only if :start was also a bp. 

Stops when it reaches the mark. This option 
requires that you use the :window option as 
well. 

Stops when it reaches point. This option 
requires that you use the :window option as 
well. 



:hack-fonts 



interval 
:kill 



:load-p 



Specifies how to treat font shifts in the buffer. 
Value Meaning 



nil 
t 



Ignores font shifts (the default). 

Provides full font support. Encodes font shifts 
on both input and output using epsilons, as 
would go to a file. 



Specifies a Zwei interval to use for the stream. 

Specifies what to do with the buffer before using it as a stream. 
Value Meaning 



nil 
t 



No action (the default) 

Deletes all the text currently in the designated 
part of the buffer. 



Specifies whether to read the file specified by rpathname into the 
editor before using the buffer as a stream. (This is analogous to 
Find File in Zmacs.) This works only from within Zmacs. 
Value Meaning 



nil 
t 



No action (the default) 
Loads the file into the editor. 



:no-redisplay 



:ordered-p 



Suppresses the redisplay of any windows associated with the 
interval being written into. 

(zwei :with-edi tor-stream 

(standard-output : buffer-name "Herald" :no-redisplay t) 

(print-herald)) 

States whether :start and :end are guaranteed to be in forward 
order. The default is nil. This applies only when :start and 
tend are bps or :point and :mark. 
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:pathname 



rstart 



: window 



Specifies a pathname to use for the stream. This can be a 
pathname object or any file spec that can be coerced to a 
pathname by fsrparse-pathname. 

Specifies where to start the stream with respect to the buffer 
contents. 

Meaning 



Value 
rappend 

:beginning 

bp 

rend 

:mark 

:point 

:region 



Starts at the end of the buffer. (Same as 
rend.) 

Starts at the beginning of the buffer. 

Starts with this bp. 

Starts at the end of the buffer (the default). 
(Same as rappend.) 

Starts at the mark, which does not move as a 
result. This requires a Zmacs window. 

Starts at point, which does not move as a 
result. This requires that you use the 
rwindow option as well. 

Starts at point and ends at mark (or vice versa, 
depending on the ordering). This requires that 
you use the rwindow option as well. It ignores 
any rend in this case. 



Specifies a Zmacs window as the stream source. 



zweirwith-editor-stream does not currently interlock to prevent simultaneous 
access to a single buffer by multiple processes. Neither does anything else. Trying 
to access the same buffer with several processes simultaneously is not guaranteed to 
work. 
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45. Making Standalone Editor Windows 



You can create an editor window with the following properties: 

• Should be standalone (have its own process). 

• Need not have the buffer structure of Zmacs. 

• Need not even have minibuffers. If I must have one, I want the pop-up style. 

• Needs a special comtab. That comtab will have commands that make the 
window do something worthwhile. 

To create such a window, follow this procedure: 

Start with zwei:standalone-editor-frame. Send it an :edit message to make it 
edit. It does not have its own process by default; you can mix tv:process-mixin 
with it and make that process send the :edit message if you want it to have its 
own process. 

Two other useful messages: 

:set-interval-string 

Inserts a string in the editor. 

:interval-string Returns a string to the caller when :edit returns. 

For providing a special comtab, you can initialize the instance variable 
zwei:*comtab* by using the :*comtab* keyword in the init plist. 

You can exit from this kind of editor by using end. 
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tv: 

fonts: 
fonts: 

tv: 



tv: 
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:keyboard-process option for 

:process-name option for 

rtypeahead option for 



:decode-variable-type method of 

.-function init option for 

:name-font init option for 

:selected-choice-font init option for 

:stack-group init option for 

:8tring-font init option for 
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:send-all-exposed-panes method of 

:send-all-panes method of 

:send-pane method of 
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timeiimezone-string function 371 

time:*timezone* variable 367 

time:verify-date function 370 

Time zone 353 

timezone-string function 371 

*timezone* variable 367 

top-box-label-mixln flavor 173 

Top edge of menu 298 

.-top init option for tv:menu 298 

rtop init option for tv:sheet 163 

top-label-mixin flavor 173 

.-top-margin-size method of tv:sheet 167 

trlOi font 140 
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truncatable-lines-mixin flavor 117 
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Truncating lines 108, 117, 119 
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tv:add-functlon-key 135 

tv:add-function-key 135 

tv:add-function-key function 135 

tv:add-select-key function 137 

tv:add-to-system-menu-create-rnenu function 239 

tv:add-to-system-menu-programs-column 
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tv.alu-seta variable 119 
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tv:autoexposing-more-mixin flavor 116 
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Wibaslc-mouse-sensitive-ltems 283 


litem-type-alist inlt option for 


tvibaslc-mouse-sensitive-items 283 


:primitlve-item method of 


tvibaslc-mouse-sensRIve-ltems 283 




tvibasic-mouse-sensitive-ltems Example 284 




tv:baaic-mouse-sensitive-items flavor 280 




tvibasic-mouse-sensitive-ttems Init-plist 




Options 283 




tvibaslc-mouse-sensitlve-Kems Messages and 




Functions 283 




tv:basic-muttiple-choice flavor 254 




tv:baslc-scroll-bar flavor 175 


.'redisplay method of 


tv.'basic-scroll-window 305 


:8et-display-item method of 


tvibasic-scroll-wlndow 305 




tv:basic-3croll-window flavor 305 


:deselected-vlslblllty inlt option for 


tv:blinker 148 


deselected-visibility method of 


tv:blinker 149 


ifollow-p init option for 


tvibllnker 148 


ihalf-period init option for 


tvibllnker 149 


.'half-period method of 


tv:blinker 149 


:read-cursorpos method of 


tv:blinker 148 


rset-cursorpos method of 


tvibllnker 148 
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tvibllnker 149 


iset-follow-p method of 


tv:blinker 148 


:set -half-period method of 


tv:blinker 149 


iset-sheet method of 


tv:blinker 149 


.'set-visibility method of 


tv:blinker 148 


visibility init option for 


tvibllnker 148 


:x-pos init option for 


tvibllnker 148 


ly-pos init option for 
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flavor 178 


.'border-margin-width init option for 


tviborders-mixin 171 


:border-margin-width method of 


tviborders-mixin 171 


:border8 init option for 


tviborders-mixin 170 


iset-border-margin-width method of 


tviborders-mixin 171 


iset-borders method of 


tviborders-mixin 171 



:set-name method of 

xhar init option for 

ifont init option for 

iset-character method of 

idocumentation specification for 

lextra-width init option for 

function init option for 

ilabel init option for 

imargin-choices init option for 

mear-mode init option for 

isuperior init option for 

iwidth init option for 



Elements of the 
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character 

icharacter-or-nil 
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tvichoose-variable-values-keyword Property 
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:date 

:date-or-never 
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:decimal-number-or-nil 

:eval-form 
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:font-llst 

:host 

:host-list 

:host-or-local 
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188 
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rdelayed-set-label method of 
:update-label method of 



:item-list-pointer inlt option for 
:update-item-list method of 



:column-8pec-list init option for 



:handle-mouse method of 

:mouse-click method of 

.-mouse-moves method of 

:center-around method of 

:expose-near method of 

:set-edges method of 
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:expose-p init option for 

:minimum-height init option for 

:minimum-width init option for 

typeout-window init option for 



Attributes of 
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:draw-circle method of 

:draw-circular-arc method of 

:draw-closed-curve method of 

:draw-cubic-spline method of 

:draw-curve method of 

:draw-dashed-line method of 

:draw-fllled-ln-circle method of 
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:draw-line method of 

:draw-lines method of 
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89 
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tv:dynamlc-...-menu 237 
tv:dynamic-rtem-list-mlxin flavor 235 
tv:dynamic-momentary-menu flavor 236 
tv:dynamic-momentary-window-hacking-menu 

flavor 236 
tv:dynamic-murticolumn-mixin 237 
tv:dynamic-multicolumn-mixin flavor 236 
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tv:essential-window 164 
tv:essential-window 107 
tv:essential-window 164 
tv:essential-window 164 
tv:essential-window-with-typeout-mixin 
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TV Fonts 145 
TV Fonts 142 
TV Fonts 140 

tv:*functlon-keys* variable 137 
tv:graphics-mixln 124 
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tv:graphics-mixin 124 
tv:graphics-mixin 125 
tv:graphics-mixin 123 
tv:graphics-mixin 122 
tv:graphics-mixin 125 
tv:graphics-mixin 125 
tv.graphics-mixin 122 
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tv:graphics-mixin 125 
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:hysteresis init option for 

:hysteresis method of 
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:helght init option for 



:label init option for 

:label-sfze method of 

:set-label method of 



:margin-choices init option for 
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The 



:set-space method o 
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:space method ol 

:activate-p init option foi 

:borders init option fo 

:bottom init option foi 
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xharacter-width init option foi 
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:deactivate method ol 
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:default-font init option foi 
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:expose-p init option foi 

:fill-p init option fo 

rflll-p method ol 

rfont-map init option fo 

:geometry init option foi 

:geometry method ol 

:helght init option foi 

Init-plist Options foi 

:inside-height init option foi 

:lnside-size init option foi 

:inside-width init option foi 

:item-li8t init option fo 

:label init option fo 

:left init option foi 
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:minimum-height init option foi 

:minimum-width init option foi 

:name init option foi 
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tv:hysteretic-window-mixln 158 
tv:hysteretic-window-mixin 158 
tv:hysteretic-window-mixin flavor 158 
tv:ibeam-blinker 150 
tv:ibeam-blinker flavor 150 
tv:item-list-pointer variable 235 
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tv:key-state function 132, 161 
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tv:label-mixin 172 
tv:label-mlxln 172 
tv:label-mixin 172 
tv:label-mixln flavor 171 
tv:line-truncating-mixin flavor 117 
tvrmake-blinker function 147 
tv:make-sheet-bft-array function 121 
tv:make-window function 107, 305 
tv:margin-choice-mixin 290 
tv:margin-choice-mlxin 290 
tv:margin*choic8-mixin Example 290 
tv:margin-choice-mixin flavor 289 
tv:margin-choice-mixin Flavor 289 
tv:margin-choice-mixin Init-plist Option 290 
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tv:margin-scroll-mlxin flavor 175 
tv:margin-space-mixin 169 
tv:margin-space-mlxin 169 
tv:margin-space-mixin 169 
tv:margin-space-mixln flavor 169 
tv:menu 295 
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:rtght init option for 

:rowt init option for 

:screen init option for 

:set-default-font method of 

:set-edges method of 

:set-flll-p method of 

:set-geometry method of 

:set-ftem-list method of 

:set-label method of 

The Flavor Network of 

fop init option for 

:vsp init option for 

rwldth init option for 

:x init option for 

:y init option for 



:add-highlighted-rtem 

:add-highlighted-value 

:hlghlighted-ltems init 

:highlighted- items 

:highlighted-values 

:remove-highlighted-item 

:remove-highlighted-value 

:set-highlighted-item8 

rset-highlighted-valuea 



method of 
method of 
option for 
method of 
method of 
method of 
method of 
method of 
method of 

Useful 
Useful 



The 



xhoose method of 
:setup method of 



tv:menu 297 

tv:menu 214, 297 

tv:menu 298 

tv:menu 299 

tv:menu 299 

tv:menu 214 

tvrmenu 214 

tvrmenu 299 

tv:menu 299 

tvrmenu 293 

tv:menu 298 

tv:menu 222, 298 

tv:menu 298 

tv:menu 298 

tv:menu 298 

tv:menu-choosa function 212, 219 

tv:menu flavor 213, 221, 293, 295, 299 

tv:menu-hlghlightlng-mlxin 243 

tv:menu-highllghting-mixin 243 

tv:menu-hlghllghting-mlxln 242 

tv:menuhlghllghting-mixin 243 

tv:menuhlghlighting-mixin 243 

tv:menu-hlghlightlng-mixin 243 

tv:menu-highlighting-mixin 243 

tv:menu-highlighting-mixin 243 

tv:menu-hlghlighting-mlxin 243 

tv:menu-hlghlighting-mlxin flavor 241 

tvrmenu Init-plist Options 222 

tv:menu Messages 223 

tv:minimum-wlndow flavor 105 

tv:momentary-menu Example 1: Simple Momentary 
Menu 223 

tv:momentary-menu Example 2: Item List as Init- 
plist Option 224 

tv:momentary-menu Example 3: Centered Label 
and Use of General List items 224 

tv:momentary-menu Example 4: Using the Mouse 
Buttons 225 

tv:momentary-menu flavor 221, 293 

tv:momentary-menu resource 221 

tv:momentary-murtip!e-menu Example 243 

tv:momentary-muHiple-menu flavor 242 

tv:momentary-window-hacking-menu flavor 221 

tv:mouse-button-encode function 156 

tv:mouse-buttons function 158 

tv:mouse-double-click-timo variable 161 

tv:*mouse-incrementing keystates* variable 161 

tv:mouse-input function 157 

tv:mouse-last-buttons variable 155 

tv:*mouse-modifying-keystates* variable 161 

tv:mou8a-sen8itive-text-8croll-window flavor 174 

tv:mouse-set-Minker-cursorpos function 152 

tv:mouse-sheet variable 152 

tv:mouse-wait function 155 

tv:mouse-wakeup function 152 

tv:mouse-x-8cale-array variable 159 

tv:mouse-x variable 155 

tv:mouse-y-or-n-p Facility 220 

tv:mouse-y-or-n-p function 220 

tv:mouse-y-8cale-array variable 160 

tv:mouse-y variable 155 

tv:muttiple-choice 255 

tv:multiple-choice 255 

tvrmurllple-cholce Example 255 

tvrmurtiple-choice flavor 254 

tv:murtiple-choice Menu Messages 255 

tv:multiple-choose function 252 
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:speclal-cholce» inlt option for 



:process inlt option for 

:helght Inlt option for 

:set-slze method of 

width Inlt option for 



type-alist inlt option for 



242 



130 
132 



ibackspace-not-overprinting-flag init option for 


tv:theet 


:baseline method of 


tvrsheet 


ftKblt-from-sheet method of 


tv:sheet 


fcitblt method of 


tv:8heet 


Attblt-wtthin-sheot method of 


tv:sheet 


:bottom init option for 


tvisheet 


:bottom-margin-size method of 


tv:sheet 


xhange-of-size-or-marglns method of 


tv:sheet 


rcharacter-height init option for 


tv:sheet 


:character-width init option for 


tv:sheel 


xharacter-width method of 


tvxheet 


:clear-char method of 


tv:sheet 


xlear-rest-oMine method of 


tv:sheet 


xlear-rest-of-window method of 


tvxheet 


xlear-wtndow method of 


tv:sheet 


:compute-motion method of 


tv:sheel 


xr-not-newline-flag init option for 


tv:sheet 


xurrent-fortt method of 


tv:sheet 


:deexposed-typein-action init option for 


tv:sheet 


:deexposed-typein-action method of 


tv.-sheet 
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tv:multiple-menu-choose-menu flavor 249 
tv:muttiple-menu-choose-menu-mixln flavor 248 
tv:multiple-menu flavor 242 
tv:muttiple-menu-mlxin 242 
tv:muttiple-menu-mixin flavor 241 
tv:muttiplo-menu-mlxln Init-plist Options 
tv:muttlple-menu-mixin Messages 243 
tv:no-8creen-managing-mixln flavor 87 
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tv:pane-mixin flavor 100, 176 
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tv:pop-up-menu Example 226 
tv:pop-up-menu flavor 221 
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tv:8«lect-or-create-window-of flavor Function 240 
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:deexposed-typeout-action method of 


tv:sheet 


116 




:delete-char method of 


tvrsheet 


t14 




:delete-line method of 


tv:sheet 


114 




rdelete-string method of 


tv:sheet 


114 




:draw-char method of 


tv:sheet 


121 




:draw-rectangle method of 


tv:sheet 


124 




:edges init option for 


tv:sheet 


163 




:edges method of 


tv:sheet 


167 




font-map init option for 


tv:8heet 
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